Creare set di dati esterni di Spanner

Questo documento descrive come creare un set di dati esterno (noto anche come set di dati federato) in BigQuery collegato a un database esistente in Spanner.

Un set di dati esterno è una connessione tra BigQuery e un'origine dati esterna a livello di set di dati. Ti consente di eseguire query sui dati transazionali nei database Spanner con GoogleSQL senza dover copiare o importare tutti i dati da Spanner allo spazio di archiviazione BigQuery. Questi risultati delle query vengono archiviati in BigQuery.

Le tabelle di un set di dati esterno vengono compilate automaticamente dalle tabelle dell'origine dati esterna corrispondente. Puoi eseguire query su queste tabelle direttamente in BigQuery, ma non puoi apportare modifiche, aggiunte o eliminazioni. Tuttavia, tutti gli aggiornamenti apportati nell'origine dati esterna vengono automaticamente riportati in BigQuery.

Quando esegui query su Spanner, i risultati delle query vengono salvati per impostazione predefinita in tabelle temporanee. Se vuoi, puoi anche salvarli come nuova tabella BigQuery, unirli ad altre tabelle o unirli a tabelle esistenti utilizzando DML.

Autorizzazioni obbligatorie

Per ottenere l'autorizzazione necessaria per creare un set di dati esterno, chiedi all'amministratore di concederti il ruolo IAM Utente BigQuery (roles/bigquery.user). Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione bigquery.datasets.create necessaria per creare un set di dati esterno.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Introduzione a IAM.

Utilizza una connessione CLOUD_RESOURCE

Se vuoi, i set di dati esterni di Spanner possono utilizzare una connessione CLOUD_RESOURCE per interagire con il tuo database Spanner, in modo da poter fornire a un utente l'accesso ai dati di Spanner tramite BigQuery, senza concedergli l'accesso diretto al database Spanner. Poiché il account di servizio della connessione CLOUD_RESOURCE gestisce il recupero dei dati da Spanner, devi solo concedere agli utenti l'accesso al set di dati esterno Spanner.

Prima di creare set di dati esterni Spanner con una connessione CLOUD_RESOURCE:

Crea una connessione

Puoi creare o utilizzare una connessione CLOUD_RESOURCE esistente per connetterti a Spanner. Per creare la connessione alla risorsa Cloud, segui i passaggi descritti nella pagina Creare una connessione a una risorsa Cloud.

Dopo aver creato la connessione, apri il riquadro Informazioni sulla connessione e copia l'ID account di servizio. Ti serve questo ID quando configuri le autorizzazioni per la connessione. Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

Configurare l'accesso

Devi concedere alla nuova connessione l'accesso in lettura all'istanza o al database Spanner. Ti consigliamo di utilizzare il ruolo IAM predefinito Cloud Spanner Database Reader with DataBoost (roles/spanner.databaseReaderWithDataBoost).

Segui questi passaggi per concedere l'accesso ai ruoli a livello di database per l'account di servizio copiato in precedenza dal collegamento:

  1. Vai alla pagina Istanze di Spanner.

    Vai alla pagina delle istanze

  2. Fai clic sul nome dell'istanza contenente il database per andare alla pagina Dettagli istanza.

  3. Nella scheda Panoramica, seleziona la casella di controllo del database.
    Viene visualizzato il riquadro Informazioni.

  4. Fai clic su Aggiungi entità.

  5. Nel riquadro Aggiungi entità, in Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.

  6. Nel campo Seleziona un ruolo, seleziona Cloud Spanner Database Reader with DataBoost role.

  7. Fai clic su Salva.

Creare un set di dati esterno

Per creare un set di dati esterno:

Console

  1. Apri la pagina BigQuery nella Google Cloud console.

    Vai alla pagina BigQuery

  2. Nel riquadro Explorer, seleziona il progetto in cui vuoi creare il set di dati.

  3. Espandi l'opzione Azioni e fai clic su Crea set di dati.

  4. Nella pagina Crea set di dati:

    • In ID set di dati, inserisci un nome univoco per il set di dati.
    • In Tipo di località, scegli una località per il set di dati, ad esempio us-central1 o multiregione us. Una volta creato un set di dati, la posizione non può essere modificata.

    • Per Set di dati esterno, segui questi passaggi:

      • Seleziona la casella accanto a Esegui il collegamento a un set di dati esterno.
      • Per Tipo di set di dati esterno, seleziona Spanner.
      • In Origine esterna, inserisci l'identificatore completo del tuo database Spanner nel seguente formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: projects/my_project/instances/my_instance/databases/my_database.
      • Se vuoi, inserisci il nome di un ruolo database Spanner in Ruolo database. Per ulteriori informazioni, leggi i ruoli del database utilizzati per la creazione di connessioni Spanner
      • Se vuoi, seleziona la casella accanto a Utilizza una connessione a una risorsa Cloud per creare il set di dati esterno con una connessione.

    • Lascia invariate le altre impostazioni predefinite.

  5. Fai clic su Crea set di dati.

SQL

Utilizza l'CREATE EXTERNAL SCHEMAistruzione DDL (Data Definition Language).

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');

    Sostituisci quanto segue:

    • DATASET_NAME: il nome del nuovo set di dati in BigQuery.
    • SPANNER_EXTERNAL_SOURCE: il nome completo e qualificato del database Spanner, con un prefisso che identifica la fonte, nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
    • LOCATION: la posizione del nuovo set di dati in BigQuery, ad esempio us-central1. Una volta creato un set di dati, non puoi modificarne la posizione.
    • (Facoltativo)CONNECTION_NAME: il nome della connessione alla risorsa Cloud.

  3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

In un ambiente a riga di comando, crea un set di dati esterno utilizzando il comando bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

In alternativa, crea un collegamento:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Sostituisci quanto segue:

  • LOCATION: la posizione del nuovo set di dati in BigQuery, ad esempio us-central1. Una volta creato un set di dati, non puoi modificarne la posizione. Puoi impostare un valore predefinito per la posizione utilizzando il file .bigqueryrc.
  • SPANNER_EXTERNAL_SOURCE: il nome completo e qualificato del database Spanner, con un prefisso che identifica la fonte, nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
  • DATASET_NAME: il nome del nuovo set di dati in BigQuery. Per creare un set di dati in un progetto diverso da quello predefinito, aggiungi l'ID progetto al nome del set di dati nel seguente formato: PROJECT_ID:DATASET_NAME.
  • (Facoltativo)CONNECTION_NAME: il nome della connessione alla risorsa Cloud.

Terraform

Utilizza la risorsa google_bigquery_dataset.

Per effettuare l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per le librerie client.

Il seguente esempio crea un set di dati esterno Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Per applicare la configurazione di Terraform in un Google Cloud progetto, completa i passaggi nelle sezioni seguenti.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il Google Cloud project predefinito in cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel main.tf appena creato.

    Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Se vuoi, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform mostri il messaggio "Applicazione completata".

  3. Apri il tuo Google Cloud progetto per visualizzare i risultati. Nella Google Cloud console, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

API

Chiama il metodo datasets.insert con una risorsa set di dati e un campo externalDatasetReference definiti per il tuo database Spanner.

Tieni presente che i nomi delle tabelle nei set di dati esterni non sono sensibili alle maiuscole.

Quando crei i set di dati esterni con una connessione CLOUD_RESOURCE, devi disporre dell'autorizzazione bigquery.connections.delegate (disponibile nel ruolo Amministratore connessione BigQuery) sulla connessione utilizzata dai set di dati esterni.

Controllare l'accesso alle tabelle

I set di dati esterni di Spanner supportano le credenziali utente finale (EUC). Ciò significa che l'accesso alle tabelle Spanner da set di dati esterni è controllato da Spanner. Gli utenti possono eseguire query su queste tabelle solo se hanno accesso concesso in Spanner.

I set di dati esterni di Spanner supportano anche la delega dell'accesso. La delega dell'accesso scinde l'accesso alle tabelle Spanner dai set di dati esterni e dall'accesso diretto alle tabelle Spanner sottostanti. Per connettersi a Spanner viene utilizzata una connessione a una risorsa Cloud associata a un account di servizio. Gli utenti possono eseguire query su queste tabelle Spanner da set di dati esterni anche se non hanno accesso concesso in Spanner.

Elenca le tabelle in un set di dati esterno

Per elencare le tabelle disponibili per le query nel set di dati esterno, consulta Elenco dei set di dati.

Ottenere informazioni sulla tabella

Per informazioni sulle tabelle del set di dati esterno, ad esempio i dettagli dello schema, consulta Ottenere informazioni sulle tabelle.

Esegui query sui dati di Spanner

L'esecuzione di query sulle tabelle nei set di dati esterni è la stessa dell'esecuzione di query sulle tabelle in qualsiasi altro set di dati BigQuery. Tuttavia, le operazioni di modifica dei dati (DML) non sono supportate.

Le query sulle tabelle dei set di dati esterni di Spanner utilizzano Data Boost per impostazione predefinita e non possono essere modificate. Di conseguenza, per eseguire queste query sono necessarie autorizzazioni aggiuntive.

Creare una visualizzazione in un set di dati esterno

Non puoi creare una visualizzazione in un set di dati esterno. Tuttavia, puoi creare una visualizzazione in un set di dati standard basato su una tabella in un set di dati esterno. Per ulteriori informazioni, consulta Creare visualizzazioni.

Eliminare un set di dati esterno

L'eliminazione di un set di dati esterno è la stessa di qualsiasi altro set di dati BigQuery. L'eliminazione dei set di dati esterni non influisce sulle tabelle nel database Spanner. Per ulteriori informazioni, consulta la sezione Eliminare i set di dati.

Limitazioni

  • Si applicano le limitazioni delle query federate di BigQuery.
  • In BigQuery sono accessibili solo le tabelle di uno schema Spanner predefinito. Le tabelle degli schemi di nomi non sono supportate.
  • Le chiavi primarie e esterne definite nel database Spanner non sono visibili in BigQuery.
  • Se una tabella nel database Spanner contiene una colonna di un tipo non supportato da BigQuery, questa colonna non sarà accessibile da BigQuery.
  • Non puoi aggiungere, eliminare o aggiornare dati o metadati nelle tabelle di un set di dati esterno Spanner.
  • Non puoi creare nuove tabelle, visualizzazioni o viste materializzate in un set di dati esterno Spanner.
  • Le visualizzazioni INFORMATION_SCHEMA non sono supportate.
  • La memorizzazione nella cache dei metadati non è supportata.
  • Le impostazioni a livello di set di dati relative ai valori predefiniti per la creazione delle tabelle non influiscono sui set di dati esterni perché non puoi creare tabelle manualmente.
  • I database Spanner che utilizzano il dialetto PostgreSQL non sono supportati.
  • Le API Write e Read non sono supportate.
  • La sicurezza a livello di riga, la sicurezza a livello di colonna e il mascheramento dei dati non sono supportati.
  • Le viste materializzate basate su tabelle di set di dati esterni Spanner non sono supportate.
  • L'integrazione con il Catalogo universale Dataplex non è supportata. Ad esempio, i profili dei dati e le analisi della qualità dei dati non sono supportati.
  • I tag a livello di tabella non sono supportati.
  • Il completamento automatico SQL non funziona con le tabelle esterne di Spanner quando scrivi query.
  • Scan with Sensitive Data Protection non è supportato per i set di dati esterni.
  • La condivisione con BigQuery sharing (in precedenza Analytics Hub) non è supportata per i set di dati esterni.
  • Se il set di dati esterno Spanner utilizza le credenziali dell'utente finale (EUC), puoi creare una vista autorizzata che fa riferimento al set di dati esterno. Tuttavia, quando viene eseguita una query su questa visualizzazione, l'EUC di una persona che esegue una query viene inviata a Spanner.
  • Se il set di dati esterno Spanner utilizza una connessione alla risorsa Cloud per la delega dell'accesso, puoi creare una vista autorizzata o una routine autorizzata che fa riferimento al set di dati esterno.

Passaggi successivi