Sincronizzare i dati BigQuery con AlloyDB

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Per informazioni sull'accesso a questa release, consulta la pagina di richiesta di accesso.

Nota: la funzionalità di sincronizzazione dei dati è supportata solo per PostgreSQL versione 18.

Questa pagina mostra come sincronizzare le tabelle da BigQuery nella tua istanza AlloyDB per PostgreSQL.

Sincronizzando i dati analitici da BigQuery in AlloyDB, puoi creare sistemi operativi che sfruttano l'accesso transazionale a bassa latenza al tuo data lake. A differenza di un foreign data wrapper (FDW) che esegue query sui dati in loco, la tabella di sincronizzazione sposta i dati nello spazio di archiviazione AlloyDB per ottenere le massime prestazioni.

AlloyDB offre i seguenti modi per spostare i dati BigQuery nella tua istanza:

• Sincronizzazione una tantum: crea una copia scrivibile e indipendente della tabella BigQuery.

• Sincronizzazione periodica (mirroring): crea una tabella locale di sola lettura che si aggiorna automaticamente in base a una pianificazione, ad esempio ogni 6 ore o ogni giorno.

Considerazioni sulle prestazioni e operative

Quando utilizzi le tabelle di sincronizzazione BigQuery, tieni presente quanto segue:

• Utilizzo delle risorse: lo spostamento dei dati consuma CPU e memoria. Per le tabelle di grandi dimensioni, valuta la possibilità di pianificare le sincronizzazioni durante le ore di punta per evitare di influire sul carico di lavoro transazionale principale.
• Visibilità dei dati: durante un'operazione di sostituzione, la tabella di destinazione esistente viene eliminata e ricreata in anticipo. Le query durante l'importazione inizialmente visualizzano una tabella vuota, seguita dai dati appena importati che vengono visualizzati in modo incrementale man mano che vengono eseguite le transazioni batch.

Prima di iniziare

1. Acquisisci familiarità con il modo in cui bigquery_fdw gestisce i tipi di dati e i mapping delle colonne BigQuery, perché l'estensione alloydb_sync utilizza bigquery_fdw per connettersi a BigQuery.
Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

2. Abilita le API Cloud necessarie per creare e connetterti ad AlloyDB.

   Abilita le API

3. Per confermare il nome del progetto a cui apporterai le modifiche, fai clic su Avanti nel passaggio Conferma progetto.

4. Nel passaggio Abilita API, fai clic su Abilita per abilitare quanto segue:

   • API AlloyDB
   • API Compute Engine
   • API Cloud Resource Manager
   • API Service Networking
   • API BigQuery Storage

   L'API Service Networking è necessaria se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova nello stesso Google Cloud progetto di AlloyDB.

   L'API Compute Engine e l'API Cloud Resource Manager sono necessarie se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova in un progetto diverso Google Cloud .

5. Assicurati di avere una tabella BigQuery esistente da cui sincronizzare i dati. Per ulteriori informazioni, consulta Creare e utilizzare le tabelle BigQuery.

Ruoli obbligatori

Per concedere all'account di servizio del cluster AlloyDB l'accesso al set di dati BigQuery, devi disporre delle seguenti autorizzazioni:

• Visualizzatore dati BigQuery (roles/bigquery.dataViewer) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.tables.get e bigquery.tables.getData. Quando viene concesso a un account di servizio, questo ruolo fornisce le autorizzazioni per leggere i dati e i metadati dalla tabella o dalla visualizzazione.
• BigQuery Read Session User (roles/bigquery.readSessionUser) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.readsessions.create e bigquery.readsessions.getData. Fornisce la possibilità di creare e utilizzare le sessioni di lettura.
• BigQuery Job User (roles/bigquery.jobUser) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.jobs.create. Fornisce la possibilità di creare ed eseguire job, inclusi i job di query.

Configurare l'estensione

Prima di sincronizzare le tabelle da BigQuery, abilita l'estensione richiesta e configura la connessione a BigQuery.

1. Crea l'estensione.

   1. Connettiti all'istanza AlloyDB utilizzando il client psql seguendo le istruzioni riportate in Connettere un client psql a un'istanza.

   2. Esegui questo comando:

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;
      

      Nota: devi creare queste estensioni in ogni database in cui vuoi sincronizzare i dati BigQuery.

2. Per consentire ad AlloyDB di eseguire l'autenticazione con BigQuery, crea il mapping utente.

   CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
   CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;
   

   Sostituisci quanto segue:

   • USER: un nome utente del database o un utente IAM che accede alla tabella BigQuery.
   • BIGQUERY_SERVER_NAME: identificatore univoco per il server BigQuery. Definisci questo valore una sola volta in un determinato database. Puoi sostituire BIGQUERY_SERVER_NAME con il nome del server.

Sincronizzare una tabella BigQuery per l'esportazione una tantum

Puoi sincronizzare una tabella BigQuery per l'esportazione una tantum utilizzando psql.

Sincronizzare una tabella BigQuery una tantum utilizzando psql

Nota: La funzione alloydb_sync.import_bq_table() crea una tabella AlloyDB scrivibile che non aggiorna automaticamente i dati da BigQuery.

Per creare una copia modificabile dei dati BigQuery, utilizza psql per eseguire la alloydb_sync.import_bq_table funzione.

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

Sostituisci quanto segue:

• PROJECT_ID: l'ID del progetto in cui si trova il set di dati BigQuery.
• DATASET_ID: il nome del set di dati BigQuery per la tabella. Per le tabelle Iceberg con un nome in 4 parti, questo è Catalog.Namespace.
• TABLE_ID: il nome della tabella o della visualizzazione BigQuery.
• ALLOYDB_DESTINATION_TABLE_NAME: il nome della tabella locale nel database AlloyDB in cui creare e importare i dati. Puoi includere il nome dello schema, ad esempio public.local_sales.
• ON_EXISTS: la strategia da utilizzare se la tabella di destinazione esiste già.
• PRIMARY_KEY_COLUMN: un elenco facoltativo di nomi di colonne da utilizzare come chiave primaria.

Esempio

L'esempio seguente mostra come sincronizzare una tabella denominata transactions da un set di dati BigQuery in una nuova tabella AlloyDB denominata public.local_sales:

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);

Parametro on_exists

Il parametro on_exists determina il modo in cui la funzione gestisce la sincronizzazione se la tabella di destinazione esiste già in AlloyDB:

• error: l'opzione predefinita. Interrompe la sincronizzazione se la tabella di destinazione esiste già.
• skip: salta la sincronizzazione se la tabella di destinazione esiste già.
• replace: sostituisce la tabella locale esistente con i dati aggiornati di BigQuery.

Supporto della chiave primaria

Se fornisci il parametro facoltativo primary_key come array di testo, AlloyDB crea la tabella con le colonne specificate come chiave primaria.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

Sincronizzare una tabella BigQuery per l'esportazione periodica

Puoi sincronizzare una tabella BigQuery per l'esportazione periodica utilizzando psql.

Creare una sincronizzazione periodica

Per mantenere una tabella di sola lettura sincronizzata con i dati BigQuery, utilizza psql per eseguire la funzione alloydb_sync.create_bq_sync_table.

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

Sostituisci quanto segue:

• PROJECT_ID.DATASET_ID.TABLE_ID: Il nome completo della tabella o della visualizzazione BigQuery, inclusi l'ID progetto, l'ID set di dati e l'ID tabella, separati da punti. Per le tabelle Iceberg con un nome in 4 parti, DATASET_ID è rappresentato come Catalog.Namespace. Ad esempio, my-gcp-project.sales_data.transactions.
• ALLOYDB_DESTINATION_TABLE_NAME: il nome della tabella locale nel database AlloyDB in cui creare e sincronizzare i dati.
• REFRESH_INTERVAL: l'intervallo in cui AlloyDB aggiorna periodicamente i dati da BigQuery, ad esempio 12 hours.
• ON_EXISTS: la strategia da utilizzare se la tabella di destinazione esiste già.
• PRIMARY_KEY_COLUMN: un elenco facoltativo di nomi di colonne da utilizzare come chiave primaria.

Esempio

L'esempio seguente mostra come creare un mirror del profilo cliente che si aggiorna ogni 12 ore:

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

Monitorare e gestire i job

Dopo aver avviato una sincronizzazione, puoi monitorarne l'avanzamento e gestire i job.

Verificare lo stato di un job

Le sincronizzazioni di grandi dimensioni possono richiedere tempo. Puoi monitorare l'avanzamento, inclusi i record elaborati e il tempo di completamento stimato, eseguendo una query sulla visualizzazione job_status:

Nota: La funzione alloydb_sync.import_bq_table() restituisce un UUID del job che puoi confrontare con import_id nella visualizzazione alloydb_sync.job_status.

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

Ad esempio, per annullare il job, esegui questo comando:

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

Interrompere ed eliminare un job di sincronizzazione

Per interrompere il mirroring di una tabella BigQuery ed eliminare la tabella locale, utilizza la funzione alloydb_sync.delete_bq_sync_table:

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

Importante: devi utilizzare questa funzione anziché i comandi DROP TABLE standard di PostgreSQL per eliminare le tabelle replicate. L'eliminazione manuale di una tabella di sincronizzazione senza questa funzione non rimuove gli hook dello scheduler in background, il che può causare errori continui e l'esaurimento degli slot dei worker in background.

Limitazioni

Quando sincronizzi le tabelle da BigQuery, si applicano le seguenti limitazioni:

• Questa funzionalità è supportata solo per PostgreSQL versione 18.
• Se DROP l'estensione alloydb_sync, devi riavviare l'istanza prima di creare di nuovo l'estensione.
• Le sincronizzazioni vengono eseguite all'interno di una transazione. Se il job di importazione viene interrotto o non riesce, il sistema esegue il rollback dei dati importati.
• Se due utenti avviano i job di sincronizzazione contemporaneamente con le stesse tabelle di destinazione, le tabelle potrebbero sovrascriversi a vicenda.
• Se si verifica un'interruzione durante l'importazione iniziale in background per una tabella di sincronizzazione appena registrata, la tabella rimane incompleta fino al successivo intervallo di aggiornamento pianificato. Per risolvere il problema, puoi eliminare la tabella di sincronizzazione utilizzando la funzione alloydb_sync.delete_bq_sync_table() e ricrearla.
• I tipi BigQuery complessi come ARRAY, BYTES, VECTOR e GEOGRAPHY non sono supportati per la sincronizzazione. Per un elenco completo, consulta Tipi di dati BigQuery supportati e mapping delle colonne.
• Non eliminare manualmente una tabella replicata. Utilizza la funzione API alloydb_sync.delete_bq_sync_table() per eliminare in sicurezza la tabella e gli aggiornamenti.
• Per eliminare un database che utilizza l'estensione alloydb_sync, devi utilizzare DROP DATABASE ... WITH (FORCE).
• Se il database Postgres si arresta in modo anomalo durante l'esecuzione di un'importazione, i metadati potrebbero rimanere bloccati nello stato RUNNING, bloccando le importazioni future. Per sbloccarlo, devi eseguire manualmente UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING';.

Prezzi

Quando sincronizzi i dati da BigQuery ad AlloyDB, ti viene addebitato il costo utilizzando i prezzi di calcolo della capacità di BigQuery.

Dopo l'esportazione dei dati, ti viene addebitato il costo per l'archiviazione dei dati in AlloyDB. Per ulteriori informazioni, consulta i prezzi di AlloyDB per PostgreSQL.

Passaggi successivi

• Scopri di più su esportazione dei dati in AlloyDB (ETL inverso).
• Scopri di più sull'esecuzione di query sui dati BigQuery in loco utilizzando FDW.