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

Per eseguire query sui dati analitici in tempo reale in BigQuery direttamente da AlloyDB per PostgreSQL senza eseguire migrazioni di estrazione, trasformazione e caricamento (ETL), puoi configurare la federazione di lakehouse. La federazione di lakehouse unifica il database operativo e il data warehouse di analisi in modo da supportare l'analisi in tempo reale e le applicazioni interattive senza dover gestire pipeline di dati separate. Per saperne di più, consulta la panoramica dell'accesso ai dati in tempo reale.

Con questa integrazione, puoi eseguire query in AlloyDB che accedono ai dati di BigQuery in tempo reale e unire le tabelle operative in AlloyDB con tabelle esterne che fanno riferimento ai tuoi set di dati BigQuery.

Prima di configurare la federazione di lakehouse, devi disporre di un cluster e un'istanza principale AlloyDB e di un set di dati e tabelle BigQuery. Per saperne di più, consulta Crea set di dati e Crea e utilizza tabelle.

Prima di iniziare

  1. Attiva il flag bigquery_fdw.enabled nell'istanza AlloyDB per PostgreSQL.
  2. Acquisisci familiarità con i tipi di dati supportati.
  3. 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 workload.

  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, if any are not already enabled.

    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, if any are not already enabled.

    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. Abilitare le API Cloud necessarie per creare e connettersi 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 è obbligatoria 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.

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 Concedi ad AlloyDB l'accesso al set di dati BigQuery.

  • BigQuery Data Viewer (roles/bigquery.dataViewer) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.tables.get e bigquery.tables.getData. Se concesso su una tabella o una vista, questo ruolo fornisce le autorizzazioni per leggere dati e metadati dalla tabella o dalla vista.
  • Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser) o qualsiasi ruolo personalizzato con le autorizzazioni bigquery.readsessions.create e bigquery.readsessions.getData. Consente di creare e utilizzare sessioni di lettura.
  • Utente job BigQuery (roles/bigquery.jobUser) o qualsiasi ruolo personalizzato con 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). Se fornisci un progetto di runtime separato, il job viene eseguito in quel progetto anziché nel progetto di dati. Ciò significa che devi concedere il ruolo Job User nel progetto di runtime.

Per accedere alle tabelle BigLake Metastore:

  • BigLake Viewer (roles/biglake.viewer) o qualsiasi ruolo personalizzato con le autorizzazioni biglake.catalogs.get, biglake.namespaces.get, biglake.tables.get e biglake.tables.getData. Fornisce le autorizzazioni per leggere cataloghi, spazi dei nomi e tabelle di BigLake Metastore.
  • Storage Object Viewer (roles/storage.objectViewer) o qualsiasi ruolo personalizzato con autorizzazioni storage.objects.get. Fornisce le autorizzazioni per accedere alle tabelle esterne di BigQuery e leggere gli oggetti Cloud Storage sottostanti che supportano le tabelle BigLake e BigLake Metastore. Deve essere concesso a livello di progetto o di bucket.

Concedi ad AlloyDB l'accesso al set di dati BigQuery

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

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

Per concedere l'accesso utilizzando gcloud CLI, segui questi passaggi:

gcloud

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

  1. Apri gcloud CLI. Se non hai installato gcloud CLI, installala e inizializzala oppure utilizza Cloud Shell.

  2. Esegui il comando gcloud beta alloydb clusters describe:

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

    Sostituisci quanto segue:

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

    L'output contiene un campo serviceAccountEmail, che è l'account di servizio 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 Controlla l'accesso alle risorse con IAM.

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

    • 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 le colonne mostra le colonne della tabella selezionata. Seleziona le colonne da 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 del processo, puoi eseguire query sulla tabella come faresti con qualsiasi tabella in AlloyDB.

psql

  1. Crea l'estensione.

    1. Connettiti all'istanza AlloyDB utilizzando il client psql seguendo le istruzioni riportate in Connetti un client psql a un'istanza. In alternativa, puoi utilizzare AlloyDB Studio. Per saperne di più, consulta Gestisci i dati utilizzando la console Google Cloud .

    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
  OPTIONS (runtime_project 'RUNTIME_PROJECT_ID');

    Sostituisci quanto segue:

    • BIGQUERY_SERVER_NAME: identificatore univoco del server esterno. Definisci questo valore una sola volta in un determinato database. Puoi sostituire BIGQUERY_SERVER_NAME con il nome del tuo server.
    • RUNTIME_PROJECT_ID: facoltativo. L'ID del progetto Google Cloudche elabora la query e matura i costi di calcolo. Se ometti questo ID, le query vengono addebitate al progetto che archivia i dati.

  3. Crea la mappatura utente eseguendo il comando CREATE USER MAPPING, che mappa un utente PostgreSQL locale che vuoi connettere 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 del server esterno che hai creato.

  4. Definisci le tabelle esterne corrispondenti 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ò contenere tutte le colonne della tabella di origine in BigQuery o un sottoinsieme di queste.

    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',
  runtime_project 'RUNTIME_PROJECT_ID'
);

    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 anche corrispondere esattamente alle 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 conservare le lettere maiuscole o miste.
    • 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 di BigQuery, consulta Mappature dei tipi di dati.
    • BIGQUERY_SERVER_NAME: identificatore univoco del server esterno che hai creato.
    • BIGQUERY_PROJECT_ID: l'ID del progetto in cui si trova il set di dati BigQuery.
    • BIGQUERY_DATASET_NAME: il nome del set di dati BigQuery per la tabella.
    • BIGQUERY_TABLE_NAME: il nome della tabella BigQuery.
    • RUNTIME_PROJECT_ID: facoltativo. L'ID del progetto Google Clouda cui fatturare l'esecuzione della query. L'impostazione di questo valore a livello di tabella sostituisce il progetto di runtime definito a livello di server.

    Dopo aver creato 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 le 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 della tabella esterna 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.

Passaggi successivi