Crea 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. Consente di eseguire query sui dati transazionali nei database Spanner con GoogleSQL senza dover copiare o importare tutti i dati da Spanner nell'archivio BigQuery. I risultati della query vengono memorizzati 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 riflessi automaticamente in BigQuery.
Quando esegui query su Spanner, i risultati vengono salvati per impostazione predefinita in tabelle temporanee. Possono anche essere salvati facoltativamente come una nuova tabella BigQuery, uniti ad altre tabelle o uniti 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 BigQuery User (roles/bigquery.user
).
Per saperne di più sulla concessione dei ruoli, consulta Gestisci 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.
Utilizzare una connessione CLOUD_RESOURCE
Se vuoi, i set di dati esterni 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 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
, procedi nel seguente modo:
Crea una connessione
Puoi creare o utilizzare una connessione CLOUD_RESOURCE
esistente per connetterti a Spanner. Per creare
la connessione risorsa Cloud, segui i passaggi descritti nella pagina Crea una connessione
risorsa Cloud.
Dopo aver creato la connessione, aprila e nel riquadro Informazioni sulla connessione, copia l'ID account di servizio. Ti servirà per configurare le autorizzazioni per la connessione. Quando crei una risorsa di connessione, BigQuery crea unaccount di serviziot di sistema univoco e lo associa alla connessione.
Configura l'accesso
Devi concedere alla nuova connessione l'accesso in lettura alla tua istanza o al tuo 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 il account di servizio che hai copiato in precedenza dalla connessione:
Vai alla pagina Istanze di Spanner.
Fai clic sul nome dell'istanza che contiene il database per accedere alla pagina Dettagli istanza.
Nella scheda Panoramica, seleziona la casella di controllo del tuo database.
Viene visualizzato il riquadro Informazioni.Fai clic su Aggiungi entità.
Nel riquadro Aggiungi entità, in Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.
Nel campo Seleziona un ruolo, seleziona Cloud Spanner Database Reader with DataBoost.
Fai clic su Salva.
Creare un set di dati esterno
Per creare un set di dati esterno:
Console
Apri la pagina BigQuery nella console Google Cloud .
Nel riquadro Explorer, seleziona il progetto in cui vuoi creare il set di dati.
Espandi l'opzione
Azioni e fai clic su Crea set di dati.Nella pagina Crea set di dati:
- In ID set di dati, inserisci un nome univoco per il set di dati.
- Per Tipo di località, scegli una località per il set di dati, ad esempio
us-central1
o multiregionaleus
. Dopo aver creato un set di dati, la posizione non può essere modificata. Per Set di dati esterno, segui questi passaggi:
- Seleziona la casella accanto a Link 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
. - (Facoltativo) Per Ruolo database, inserisci il nome di un ruolo database di Spanner. 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 alla risorsa Cloud per creare il set di dati esterno con una connessione.
Lascia invariate le altre impostazioni predefinite.
Fai clic su Crea set di dati.
SQL
Utilizza l'istruzione DDL (Data Definition Language).CREATE EXTERNAL SCHEMA
Nella console Google Cloud , vai alla pagina BigQuery.
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 l'origine, 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
ogoogle-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database
.LOCATION
: la posizione del nuovo set di dati in BigQuery, ad esempious-central1
. Dopo aver creato un set di dati, non puoi modificarne la posizione.- (Facoltativo)
CONNECTION_NAME
: il nome della connessione alla risorsa Cloud.
Fai clic su
Esegui.
Per maggiori informazioni su come eseguire le 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 con una connessione:
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 esempious-central1
. Dopo aver creato un set di dati, non puoi modificarne la posizione. Puoi impostare un valore di posizione predefinito utilizzando il file.bigqueryrc
.SPANNER_EXTERNAL_SOURCE
: il nome completo e qualificato del database Spanner, con un prefisso che identifica l'origine, 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
ogoogle-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 eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
L'esempio seguente crea un set di dati esterno Spanner:
Per applicare la configurazione di Terraform in un progetto Google Cloud , completa i passaggi nelle sezioni seguenti.
Prepara Cloud Shell
- Avvia Cloud Shell.
-
Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.
Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo 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 la propria directory (chiamata anche modulo radice).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione
.tf
, ad esempiomain.tf
. In questo tutorial, il file viene denominatomain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.
Copia il codice campione nel
main.tf
appena creato.(Facoltativo) Copia il codice da GitHub. Questa operazione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
- Rivedi e modifica i parametri di esempio da applicare al tuo ambiente.
- Salva le modifiche.
-
Inizializza Terraform. Devi effettuare questa operazione una sola volta per directory.
terraform init
(Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione
-upgrade
:terraform init -upgrade
Applica le modifiche
-
Rivedi la configurazione e verifica che le risorse che Terraform creerà o
aggiornerà corrispondano alle tue aspettative:
terraform plan
Apporta le correzioni necessarie alla configurazione.
-
Applica la configurazione di Terraform eseguendo il comando seguente e inserendo
yes
al prompt:terraform apply
Attendi che Terraform visualizzi il messaggio "Apply complete!" (Applicazione completata).
- Apri il tuo Google Cloud progetto 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 dataset definita e il campo externalDatasetReference
per il tuo database Spanner.
Tieni presente che i nomi delle tabelle nei set di dati esterni non fanno distinzione tra maiuscole e minuscole.
Quando crei i set di dati esterni con una connessione CLOUD_RESOURCE
, devi disporre dell'autorizzazione bigquery.connections.delegate
(disponibile dal ruolo Amministratore connessione BigQuery) per la 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 Spanner supportano anche la delega dell'accesso. La delega dell'accesso disaccoppia l'accesso alle tabelle Spanner dai set di dati esterni e l'accesso diretto alle tabelle Spanner sottostanti. Una connessione a una risorsa Cloud associata a un account di servizio viene utilizzata per connettersi a Spanner. 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, vedi Elenco dei set di dati.
Recuperare informazioni sulla tabella
Per ottenere informazioni sulle tabelle nel set di dati esterno, ad esempio i dettagli dello schema, consulta Ottenere informazioni sulle tabelle.
Esegui query sui dati Spanner
L'esecuzione di query sulle tabelle nei set di dati esterni è uguale all'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 nei set di dati esterni Spanner utilizzano Data Boost per impostazione predefinita e non possono essere modificate. Per questo motivo, 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 saperne di più, consulta Creare viste.
Eliminare un set di dati esterno
L'eliminazione di un set di dati esterno è uguale all'eliminazione di qualsiasi altro set di dati BigQuery. L'eliminazione di set di dati esterni non influisce sulle tabelle nel database Spanner. Per saperne di più, 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 denominati non sono supportate.
- Le chiavi primarie ed 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 sul lato BigQuery.
- Non puoi aggiungere, eliminare o aggiornare dati o metadati nelle tabelle di un dataset esterno Spanner.
- Non puoi creare nuove tabelle, viste o viste materializzate in un set di dati esterno Spanner.
- Le
INFORMATION_SCHEMA
visualizzazioni non sono supportate. - La memorizzazione nella cache dei metadati non è supportata.
- Le impostazioni a livello di set di dati correlate ai valori predefiniti di creazione delle tabelle non influenzano i set di dati esterni perché non puoi creare tabelle manualmente.
- I database Spanner che utilizzano il dialetto PostgreSQL non sono supportati.
- L'API Write e l'API 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 Universal Catalog non è supportata. Ad esempio, i profili dei dati e le scansioni della qualità dei dati non sono supportati.
- I tag a livello di tabella non sono supportati.
- Il completamento automatico di SQL non funziona con le tabelle esterne Spanner quando scrivi query.
- L'opzione Analizza con Sensitive Data Protection non è supportata 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, le EUC di una persona che esegue una query vengono inviate a Spanner.
- Se il set di dati esterno Spanner utilizza una connessione 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
- Scopri di più sulle query federate Spanner.