Creare set di dati esterni 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 spostare i dati da Spanner allo spazio di archiviazione 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.

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.

Creare un set di dati esterno

Per creare un set di dati esterno:

Console

  1. Apri la pagina BigQuery nella console Google Cloud.

    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:

      • 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

    • 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');

    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.

  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

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.

Terraform

Utilizza la risorsa google_bigquery_dataset.

Per autenticarti in BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

Il seguente esempio crea un set di dati esterno Spanner:

resource "google_bigquery_dataset" "dataset" {
  provider                    = google-beta
  dataset_id                  = "example_dataset"
  friendly_name               = "test"
  description                 = "This is a test description."
  location                    = "us-central1"

external_dataset_reference {
  external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
  }
}

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

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud 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 file 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 progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, 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 per il tuo database Spanner.

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

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.

Recuperare le informazioni della tabella

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

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.

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.
  • 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 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 Analytics Hub non è supportata per i set di dati esterni.
  • Puoi creare una vista autorizzata che fa riferimento al set di dati esterno Spanner. Tuttavia, quando viene eseguita una query su questa visualizzazione, l'EUC di una persona che esegue una query viene inviata a Spanner.

Passaggi successivi