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 nell'istanza AlloyDB per PostgreSQL.

Sincronizzando i dati analitici da BigQuery in AlloyDB, puoi creare sistemi operativi che beneficiano dell'accesso transazionale a bassa latenza al tuo data lake. A differenza di un wrapper di dati esterni (FDW) che esegue query sui dati sul posto, 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 indipendente e scrivibile della tua 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 operative e sulle prestazioni

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 molto grandi, valuta la possibilità di pianificare le sincronizzazioni durante le ore non di punta per evitare di influire sul workload 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 nuovi dati 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 account Google Cloud . 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 progetto Google Cloud 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 Google Cloud diverso.

5. Assicurati di avere una tabella BigQuery esistente da cui sincronizzare i dati. Per saperne di più, consulta Creare e utilizzare tabelle BigQuery.

Ruoli obbligatori

Per concedere l'accesso al set di dati BigQuery al account di servizio del cluster AlloyDB, 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. Se concesso a un account di servizio, questo ruolo fornisce le autorizzazioni per leggere dati e metadati dalla tabella o dalla visualizzazione.
• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.readsessions.create e bigquery.readsessions.getData. Fornisce la possibilità di creare e utilizzare sessioni di lettura.
• Utente job BigQuery (roles/bigquery.jobUser) o qualsiasi ruolo personalizzato con autorizzazioni bigquery.jobs.create. Offre la possibilità di creare ed eseguire job, inclusi i job di query.

Configurare l'estensione

Prima di sincronizzare le tabelle da BigQuery, attiva l'estensione richiesta e configura la connessione a BigQuery. Se utilizzi la console Google Cloud , AlloyDB esegue questi passaggi automaticamente.

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 autenticarsi 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 questa impostazione una sola volta in un determinato database. Puoi sostituire BIGQUERY_SERVER_NAME con il nome del tuo server.

Sincronizza una tabella BigQuery per l'esportazione una tantum

Puoi sincronizzare una tabella BigQuery per l'esportazione una tantum utilizzando la consoleGoogle Cloud o psql.

Utilizzare la Google Cloud console

Per sincronizzare una tabella BigQuery con AlloyDB utilizzando la consoleGoogle Cloud :

1. Apri la pagina BigQuery nella console Google Cloud .

   Vai alla pagina BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro a sinistra per aprirlo.

3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati e poi sul tuo set di dati.

4. Fai clic su Panoramica > Tabelle e seleziona una tabella.

5. Nel riquadro dei dettagli, fai clic su Carica Esporta / Sincronizza > AlloyDB (Esporta una volta o sincronizza).

6. In Scegli un cluster di destinazione, seleziona una delle seguenti opzioni:

   • Seleziona Utilizza un cluster esistente per esportare la tabella BigQuery in un cluster AlloyDB esistente. Poi, procedi nel seguente modo:

     1. Seleziona il cluster AlloyDB principale.

     2. Seleziona il database AlloyDB di destinazione.

     3. Seleziona lo schema per la tabella AlloyDB di destinazione.

     4. Specifica un nome per la tabella AlloyDB di destinazione.

     5. Per Frequenza di sincronizzazione, seleziona Una sola volta per creare una copia della tabella BigQuery.

     6. Fai clic su Configura esportazione.

     Al termine della configurazione della sincronizzazione, puoi utilizzare le istruzioni SQL fornite per monitorare il job di importazione ed eseguire query sulle tabelle importate. Fai clic su Query per visualizzare la tabella importata in AlloyDB Studio.

   • Seleziona Crea un nuovo cluster per esportare la tabella BigQuery in un nuovo cluster AlloyDB. Quindi:

     1. Fai clic su Configura esportazione.

     2. Nella finestra di dialogo Reindirizza ad AlloyDB, seleziona Reindirizza.

     3. Seleziona un tipo di cluster: Cluster di prova senza costi o Cluster di cui è stato eseguito il provisioning.

     4. Fai clic su Continua.

     5. In Configurazione della sincronizzazione, seleziona il database AlloyDB di destinazione postgres predefinito, lo schema public predefinito per la tabella AlloyDB di destinazione e specifica un nome per la tabella AlloyDB di destinazione.

        Per Frequenza di sincronizzazione, seleziona Una sola volta per creare una copia della tabella BigQuery.

     6. Fai clic su Continua.

     7. Configura il cluster. Per saperne di più su ciascun campo, vedi Crea un nuovo cluster e un'istanza primaria.

     8. Fai clic su Crea cluster.

     Al termine della configurazione della sincronizzazione, vai ad AlloyDB Studio per eseguire query sulle tabelle importate.

Sincronizzare una tabella BigQuery una sola volta 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 funzione alloydb_sync.import_bq_table.

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 quattro parti, questo è Catalog.Namespace.
• TABLE_ID: il nome della tabella o della vista 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 la modalità di gestione della sincronizzazione da parte della funzione se la tabella di destinazione esiste già in AlloyDB:

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

Supporto delle chiavi primarie

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 la consoleGoogle Cloud o psql.

Utilizzare la Google Cloud console

Per sincronizzare una tabella BigQuery con AlloyDB utilizzando la consoleGoogle Cloud :

1. Apri la pagina BigQuery nella console Google Cloud .

   Vai alla pagina BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro a sinistra per aprirlo.

3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati e poi sul tuo set di dati.

4. Fai clic su Panoramica > Tabelle e seleziona una tabella.

5. Nel riquadro dei dettagli, fai clic su Carica Esporta / Sincronizza > AlloyDB (Esporta una volta o sincronizza).

6. In Scegli un cluster di destinazione, seleziona una delle seguenti opzioni:

   • Seleziona Utilizza un cluster esistente per esportare la tabella BigQuery in un cluster AlloyDB esistente. Poi, procedi nel seguente modo:

     1. Seleziona il cluster AlloyDB principale.

     2. Seleziona il database AlloyDB di destinazione.

     3. Seleziona lo schema per la tabella AlloyDB di destinazione.

     4. Specifica un nome per la tabella AlloyDB di destinazione.

     5. Per Frequenza di sincronizzazione, seleziona un periodo di tempo per creare una sincronizzazione periodica della tabella BigQuery, ad esempio Ogni ora o Ogni sei ore.

     6. Fai clic su Configura esportazione.

     Al termine della configurazione della sincronizzazione, puoi utilizzare le istruzioni SQL fornite per monitorare il job di importazione ed eseguire query sulla tabella importata. Fai clic su Query per visualizzare la tabella importata in AlloyDB Studio.

   • Seleziona Crea un nuovo cluster per esportare la tabella BigQuery in un nuovo cluster AlloyDB. Quindi:

     1. Fai clic su Configura esportazione.

     2. Nella finestra di dialogo Reindirizza ad AlloyDB, seleziona Reindirizza.

     3. Seleziona un tipo di cluster: Cluster di prova senza costi o Cluster di cui è stato eseguito il provisioning.

     4. Fai clic su Continua.

     5. In Configurazione della sincronizzazione, seleziona il database AlloyDB di destinazione postgres predefinito, lo schema public predefinito per la tabella AlloyDB di destinazione e specifica un nome per la tabella AlloyDB di destinazione.

        Per Frequenza di sincronizzazione, seleziona Una sola volta per creare una copia della tabella BigQuery.

     6. Fai clic su Continua.

     7. Configura il cluster. Per saperne di più su ciascun campo, vedi Crea un nuovo cluster e un'istanza primaria.

     8. Fai clic su Crea cluster.

     Al termine della configurazione della sincronizzazione, vai ad AlloyDB Studio per eseguire query sulle tabelle importate.

Crea 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 quattro 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.

Verifica dello stato di un job

Le sincronizzazioni di grandi dimensioni possono richiedere tempo. Puoi monitorare l'avanzamento, inclusi i record elaborati e il tempo stimato per il completamento, eseguendo query sulla vista 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 PostgreSQL standard 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 dello scheduler e l'esaurimento degli slot dei worker in background.

Mappature dei tipi di dati

Quando sincronizzi o importi dati da BigQuery ad AlloyDB utilizzando l'estensione alloydb_sync, AlloyDB mappa i tipi di dati BigQuery ai tipi di dati PostgreSQL corrispondenti nella tabella di destinazione.

Verifica che le colonne della tabella BigQuery di origine utilizzino i seguenti tipi di dati supportati.

La tabella seguente elenca i mapping dei tipi di dati tra BigQuery e AlloyDB.

Tipi di dati della tabella BigQuery	Tipi di dati delle tabelle esterne PostgreSQL consigliati
BOOLEAN	BOOLEAN
INTEGER (INT64)	BIGINT
FLOAT (FLOAT64)	DOUBLE PRECISION
STRING	VARCHAR
NUMERIC	NUMERIC(38, 9)
NUMERIC(P[, S])	NUMERIC(P, S)
BIGNUMERIC	NUMERIC(77, 38)
BIGNUMERIC(P[, S])	NUMERIC(P, S)
DATE	DATE
TIMESTAMP	TIMESTAMPTZ
TIME	TIME
JSON	JSONB
BYTES	BYTEA
GEOGRAPHY	GEOGRAPHY(POINT), ... Per saperne di più, consulta PostGIS_Geography.
DATETIME	TIMESTAMP
ARRAY	VECTOR(N) N è la dimensione del vettore. Devi impostare il flag bigquery_fdw.enable_vector_downcasting nella sessione. Poiché il tipo VECTOR in AlloyDB utilizza il tipo float4, potresti riscontrare una perdita di precisione in questa conversione. Per saperne di più, consulta l'estensione pgvector.

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 ricrearla.
• Le sincronizzazioni vengono eseguite all'interno di una transazione. Se il job di importazione viene interrotto o non va a buon fine, il sistema esegue il rollback dei dati importati.
• Se due utenti avviano 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 di 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 e mappature delle colonne di BigQuery supportati.
• Non eliminare manualmente una tabella replicata. Utilizza la funzione API alloydb_sync.delete_bq_sync_table() per eliminare in modo sicuro 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 bloccarsi nello stato RUNNING, impedendo le importazioni future. Devi eseguire manualmente UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; per sbloccarlo.

Prezzi

Quando sincronizzi i dati da BigQuery ad AlloyDB, ti viene addebitato l'utilizzo dei prezzi delle letture in streaming di BigQuery (API Storage Read).

Una volta esportati i dati, ti vengono addebitati i costi per l'archiviazione in AlloyDB. Per saperne di più, consulta la sezione Prezzi di AlloyDB per PostgreSQL.

Passaggi successivi

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