Configura l'accesso di AlloyDB ai dati in tempo reale in BigQuery

Questo documento spiega come implementare la federazione lakehouse, una funzionalità che consente di eseguire query sui dati live in BigQuery direttamente da AlloyDB senza eseguire migrazioni ETL (estrazione, trasformazione, caricamento) complesse. La federazione lakehouse unifica i datastore operativi e analitici, eliminando la necessità di pipeline di dati complesse e soggette a errori. Per saperne di più, consulta Panoramica dell'accesso ai dati in tempo reale.

Integrando AlloyDB e BigQuery, puoi ottenere un flusso continuo di dati tra il database transazionale e il data warehouse, che supporta l'analisi in tempo reale e ti aiuta a creare potenti applicazioni interattive.

Puoi utilizzare questa integrazione per eseguire query in AlloyDB che accedono ai dati BigQuery in tempo reale. Puoi eseguire join tra le tabelle in AlloyDB e le tabelle esterne che fanno riferimento ai set di dati BigQuery. Questa funzionalità è utile quando hai bisogno dei dati più recenti di BigQuery senza spostarli.

Questa pagina presuppone che tu disponga di un cluster AlloyDB e di un'istanza principale, nonché di un set di dati e di tabelle BigQuery. Per saperne di più, consulta Creare set di dati e Creare e utilizzare tabelle.

Prima di iniziare

  1. Abilita il bigquery_fdw.enabled flag sull' istanza AlloyDB per PostgreSQL.
  2. Acquisisci familiarità con i tipi di dati supportati.
  3. Accedi al tuo Google Cloud account. Se non hai mai utilizzato 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 eseguire, testare e implementare i carichi di lavoro.

  4. 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.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

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

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    10.

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

    Abilita le API

  11. Nel passaggio Conferma progetto, fai clic su Avanti per confermare il nome del progetto a cui apporterai le modifiche.

  12. 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
    • API BigQuery

    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 .

Ruoli obbligatori

Per concedere l'accesso in lettura al set di dati BigQuery al account di servizio del cluster AlloyDB, devi disporre delle seguenti autorizzazioni. Per saperne di più, consulta Concedere ad AlloyDB l'accesso al set di dati BigQuery.

  • Visualizzatore dati BigQuery (roles/bigquery.dataViewer) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.tables.get e bigquery.tables.getData. Quando viene concesso a una tabella o a una vista, questo ruolo fornisce le autorizzazioni per leggere i dati e i metadati dalla tabella o dalla vista.
  • 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 sessioni di lettura.
  • BigQuery Job User (roles/bigquery.jobUser) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.jobs.create. Fornisce le autorizzazioni per eseguire job, incluse le query, all'interno del progetto utilizzando l'API BigQuery. Questo ruolo può essere concesso solo alle risorse di Resource Manager (progetti, cartelle e organizzazioni).
  • Visualizzatore oggetti Storage (roles/storage.objectViewer) o qualsiasi ruolo personalizzato con le autorizzazioni storage.objects.get. Fornisce le autorizzazioni per accedere alle tabelle esterne BigQuery. Deve essere concesso a livello di progetto o bucket.

Concedere ad AlloyDB l'accesso al set di dati BigQuery

Dopo aver abilitato i ruoli e le autorizzazioni richiesti per la federazione lakehouse, devi concedere al account di servizio del cluster AlloyDB l'accesso al set di dati BigQuery.

La Google Cloud console concede automaticamente le autorizzazioni richieste al account di servizio del cluster quando connetti una tabella BigQuery utilizzando AlloyDB Studio.

Per concedere l'accesso utilizzando gcloud CLI:

gcloud

Per utilizzare gcloud CLI, puoi installare e inizializzare Google Cloud CLI oppure utilizzare Cloud Shell.

  1. Apri gcloud CLI. Se non hai installato gcloud CLI, installalo e inizializzalo oppure utilizza Cloud Shell.

  2. Esegui il gcloud beta alloydb clusters describe comando:

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

    Sostituisci quanto segue:

    • CLUSTER: l'ID del cluster AlloyDB.
    • REGION: la località del cluster AlloyDB, ad esempio asia-east1, us-east1. Visualizza l'elenco completo delle regioni in Località AlloyDB.

    L'output contiene un campo serviceAccountEmail, che è il service account per questo cluster. Puoi trovare il account di servizio anche nella pagina Panoramica del cluster.

  3. Concedi le autorizzazioni richieste. Per saperne di più, consulta Controllare l'accesso alle risorse con IAM.

    Se il account di servizio del cluster non dispone delle autorizzazioni richieste, vengono visualizzati i seguenti errori quando viene eseguita una query sulla tabella BigQuery:

    • The user does not have bigquery.readsessions.create permissions
    • Permission bigquery.tables.get denied on table
    • Permission bigquery.tables.getData denied on table

Configurare l'estensione

Per configurare l'estensione:

Console

  1. Vai alla pagina Cluster.

    Vai a Cluster

  2. Fai clic sull'ID del cluster che vuoi utilizzare.

  3. Nel menu di navigazione, fai clic su AlloyDB Studio.

  4. Accedi al tuo database.

  5. Nel riquadro Explorer, espandi lo schema pertinente.

  6. Fai clic sul menu Azioni accanto a Tabelle BigQuery e poi su Connetti tabella BigQuery.

  7. Nel riquadro Connetti tabella BigQuery , scegli un progetto di origine, un set di dati di origine e una tabella.

  8. La tabella Esamina e seleziona colonne mostra le colonne della tabella selezionata. Seleziona le colonne che vuoi mappare.

  9. Nel campo Nome tabella, inserisci un nome per la tabella esterna.

  10. (Facoltativo) Fai clic su Visualizza comando SQL per visualizzare il comando generato.

  11. Fai clic su Connetti tabella. Viene visualizzata una finestra di dialogo che mostra l'avanzamento. Al termine della procedura, puoi eseguire query sulla tabella come su qualsiasi tabella in AlloyDB.

psql

  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. In alternativa, puoi utilizzare AlloyDB Studio. Per saperne di più, consulta Gestire i dati utilizzando la Google Cloud console.

    2. Esegui questo comando:

      CREATE EXTENSION bigquery_fdw;

  2. Crea un server esterno per definire i parametri di connessione per il set di dati BigQuery remoto.

    CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;

    Sostituisci quanto segue:

    • BIGQUERY_SERVER_NAME: identificatore univoco per il server esterno. Definisci questo valore una volta in un determinato database. Puoi sostituire BIGQUERY_SERVER_NAME con il nome del server.

  3. Crea la mappatura utente eseguendo il comando CREATE USER MAPPING, che mappa un utente PostgreSQL locale a cui vuoi connetterti al server esterno.

    CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;

    Sostituisci quanto segue:

    • USERNAME: un nome utente del database o un utente IAM che accede alla tabella esterna.
    • BIGQUERY_SERVER_NAME: identificatore univoco per il server esterno che hai creato.

  4. Definisci le tabelle esterne che corrispondono alle tabelle a cui vuoi accedere in BigQuery utilizzando il comando CREATE FOREIGN TABLE. Questo comando consente di definire la struttura di una tabella remota. La tabella esterna può avere tutte o un sottoinsieme delle colonne della tabella di origine in BigQuery.

    CREATE FOREIGN TABLE TABLENAME (
COLUMN1_NAME DATA_TYPE,
COLUMN2_NAME DATA_TYPE,
... ) SERVER BIGQUERY_SERVER_NAME OPTIONS (project BIGQUERY_PROJECT_ID,
dataset BIGQUERY_DATASET_NAME,
table BIGQUERY_TABLE_NAME);

    Sostituisci quanto segue:

    • TABLENAME: il nome della tabella esterna nel database AlloyDB locale.
    • COLUMNX_NAME: il nome della colonna AlloyDB. Il nome della colonna deve corrispondere esattamente al nome della colonna corrispondente nella tabella di origine BigQuery. X indica che la tabella può essere creata con più colonne. Il nome deve corrispondere anche alla distinzione tra maiuscole e minuscole della colonna BigQuery. Se il nome della colonna BigQuery contiene lettere maiuscole (ad esempio, employeeID), l'identificatore AlloyDB deve essere racchiuso tra virgolette doppie (ad esempio, "employeeID") per preservare le lettere miste o maiuscole.
    • DATA_TYPE: il tipo di dati della colonna. Quando definisci DATA_TYPE per ogni colonna della tabella esterna, verifica che sia un tipo PostgreSQL compatibile. Per saperne di più su come vengono convertiti i tipi BigQuery, consulta Mappature dei tipi di dati.
    • BIGQUERY_SERVER_NAME: identificatore univoco per il server esterno che hai creato.
    • BIGQUERY_PROJECT_ID: ID del progetto in cui si trova il set di dati BigQuery.
    • BIGQUERY_DATASET_NAME: nome del set di dati BigQuery per la tabella.
    • BIGQUERY_TABLE_NAME: nome della tabella BigQuery.

    Una volta creata la tabella esterna, puoi eseguire query su questa tabella nello stesso modo in cui esegui query su qualsiasi tabella in AlloyDB.

Mappature dei tipi di dati

Utilizza la tabella seguente per scoprire di più sulle mappature dei tipi di dati tra BigQuery e AlloyDB. Per saperne di più, consulta Considerazioni sui tipi di dati per le query federate.

La tabella seguente elenca le mappature dei tipi di dati tra BigQuery e AlloyDB.

Tipi di dati delle tabelle 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 bigquery_fdw.enable_vector_downcasting flag 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.

Passaggi successivi