Creazione di tabelle BigLake di Cloud Storage
Questo documento descrive come creare una tabella BigLake di Cloud Storage. Una tabella BigLake consente di utilizzare la delega di accesso per eseguire query su dati strutturati in Cloud Storage. La delega di accesso disaccoppia l'accesso alla tabella BigLake dall'accesso al datastore sottostante.
Prima di iniziare
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Attiva BigQuery Connection API.
Se vuoi leggere le tabelle BigLake da motori open source come Apache Spark, devi abilitare l'API BigQuery Storage Read.
-
Nella console Google Cloud, attiva Cloud Shell.
Assicurati di avere un set di dati BigQuery.
Assicurati che la tua versione di Google Cloud SDK sia 366.0.0 o successiva:
gcloud version
Se necessario, aggiorna Google Cloud SDK.
- (Facoltativo) Per Terraform, è necessaria la versione
terraform-provider-google
4.25.0 o successive. Le release perterraform-provider-google
sono elencate su GitHub. Puoi scaricare la versione più recente di Terraform dai download di Terraform per HashiCorp.
- (Facoltativo) Per Terraform, è necessaria la versione
Creare una connessione a risorse cloud basata sull'origine dati esterna e concedere a questa connessione l'accesso a Cloud Storage. Se non disponi delle autorizzazioni appropriate per creare una connessione, chiedi all'amministratore BigQuery di creare una connessione e di condividerla con te.
Ruoli obbligatori
Per creare una tabella BigLake, devi disporre delle seguenti autorizzazioni IAM (Identity and Access Management) di BigQuery:
bigquery.tables.create
bigquery.connections.delegate
Il ruolo predefinito Amministratore BigQuery (roles/bigquery.admin
) di Identity and Access Management include queste autorizzazioni.
Se non sei un'entità in questo ruolo, chiedi all'amministratore di concederti l'accesso o di creare la tabella BigLake per te.
Per ulteriori informazioni sui ruoli e sulle autorizzazioni di Identity and Access Management in BigQuery, consulta Ruoli e autorizzazioni predefiniti.
Considerazione località
Quando utilizzi Cloud Storage per archiviare i file di dati, puoi migliorare le prestazioni utilizzando bucket Cloud Storage per una singola regione o due regioni anziché bucket multiregionali.
Creazione di tabelle BigLake su dati non partizionati
Se hai dimestichezza con la creazione di tabelle in BigQuery, il processo di creazione di una tabella BigLake è simile. La tabella può utilizzare qualsiasi formato file supportato da BigLake. Per saperne di più, consulta la sezione Limitazioni.
Prima di creare una tabella BigLake, devi avere un set di dati e una connessione alle risorse Cloud che possano accedere a Cloud Storage.
Per creare una tabella BigLake, seleziona una delle seguenti opzioni:
Console
Vai alla pagina BigQuery.
Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
Espandi l'opzione
Azioni e fai clic su Crea tabella.Nella sezione Origine, specifica i seguenti dettagli:
In Crea tabella da, seleziona Google Cloud Storage
In Seleziona file dal bucket GCS o utilizza un pattern URI, sfoglia per selezionare un bucket e un file da utilizzare oppure digita il percorso nel formato
gs://bucket_name/[folder_name/]file_name
.Non puoi specificare più URI nella console Google Cloud, ma puoi selezionare più file specificando un carattere jolly asterisco (
*
). Ad esempio,gs://mybucket/file_name*
. Per ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella che stai creando.
Per Formato file, seleziona il formato corrispondente al tuo file.
Nella sezione Destinazione, specifica i seguenti dettagli:
In Progetto, scegli il progetto in cui creare la tabella.
Per Set di dati, scegli il set di dati in cui creare la tabella.
In Tabella, inserisci il nome della tabella che stai creando.
Per Tipo di tabella, seleziona Tabella esterna.
Seleziona Crea una tabella BigLake utilizzando una connessione a una risorsa cloud.
Per ID connessione, seleziona la connessione che hai creato in precedenza.
Nella sezione Schema, puoi abilitare il rilevamento automatico dello schema o specificare manualmente uno schema se disponi di un file di origine. Se non hai un file di origine, devi specificare manualmente uno schema.
Per attivare il rilevamento automatico dello schema, seleziona l'opzione Rilevamento automatico.
Per specificare manualmente uno schema, lascia deselezionata l'opzione Rilevamento automatico. Abilita Modifica come testo e inserisci lo schema della tabella come array JSON.
Per ignorare le righe con valori di colonna aggiuntivi che non corrispondono allo schema, espandi la sezione Opzioni avanzate e seleziona Valori sconosciuti.
Fai clic su Crea tabella.
Dopo aver creato la tabella permanente, puoi eseguire una query sulla tabella come se fosse una tabella BigQuery nativa. Una volta completata la query, puoi esportare i risultati come file CSV o JSON, salvarli come tabella o in Fogli Google.
SQL
Utilizza l'istruzione DDL CREATE EXTERNAL TABLE
.
Puoi specificare lo schema in modo esplicito o utilizzare il rilevamento automatico dello schema per dedurre lo schema dai dati esterni.
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor query, inserisci la seguente istruzione:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID` OPTIONS ( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'[,...]], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
Sostituisci quanto segue:
PROJECT_ID
: il nome del progetto in cui vuoi creare la tabella, ad esempiomyproject
DATASET
: il nome del set di dati BigQuery in cui vuoi creare la tabella, ad esempiomydataset
EXTERNAL_TABLE_NAME
: il nome della tabella che vuoi creare, ad esempiomytable
REGION
: la regione che contiene la connessione, ad esempious
CONNECTION_ID
: l'ID connessione, ad esempiomyconnection
Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
.TABLE_FORMAT
: il formato della tabella che vuoi creare, ad esempioPARQUET
Per maggiori informazioni sui formati supportati, consulta Limitazioni.
BUCKET_PATH
: il percorso del bucket Cloud Storage che contiene i dati per la tabella esterna, nel formato['gs://bucket_name/[folder_name/]file_name']
.Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (
*
) nel percorso. Ad esempio,['gs://mybucket/file_name*']
. Per maggiori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi.I seguenti esempi mostrano valori
uris
validi:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
Quando specifichi valori
uris
che hanno come target più file, tutti questi file devono condividere uno schema compatibile.Per maggiori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa di Cloud Storage.
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e la frequenza di aggiornamento dei metadati memorizzati nella cache affinché l'operazione li utilizzi. Per maggiori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore letterale a intervalli compreso tra 30 minuti e 7 giorni. Ad esempio, specifica
INTERVAL 4 HOUR
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta la pagina relativa alla memorizzazione dei metadati per le prestazioni.Imposta
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
bq
Opzione 1: file di definizione tabella
Utilizza il comando bq mkdef
per creare un file di definizione della tabella, quindi passa il percorso del file al comando bq mk
come segue:
bq mkdef \ --connection_id=CONNECTION_ID \ --source_format=SOURCE_FORMAT \ BUCKET_PATH > DEFINITION_FILE bq mk --table \ --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
CONNECTION_ID
: l'ID connessione, ad esempiomyconnection
Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
.SOURCE_FORMAT
: il formato dell'origine dati esterna. Ad esempio,PARQUET
.BUCKET_PATH
: il percorso del bucket Cloud Storage che contiene i dati per la tabella, nel formatogs://bucket_name/[folder_name/]file_pattern
.Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (
*
) infile_pattern
. Ad esempio:gs://mybucket/file00*.parquet
. Per ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi.I seguenti esempi mostrano valori
uris
validi:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Quando specifichi valori
uris
che hanno come target più file, tutti questi file devono condividere uno schema compatibile.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso risorsa di Cloud Storage.
DEFINITION_FILE
: il percorso del file di definizione della tabella sulla macchina locale.STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e la quantità di metadati memorizzati nella cache affinché l'operazione li utilizzi. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni utilizzando il formato
Y-M D H:M:S
descritto nella documentazione sui tipi di datiINTERVAL
. Ad esempio, specifica0-0 0 4:0:0
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.DATASET
: il nome del set di dati BigQuery in cui vuoi creare una tabella, ad esempiomydataset
EXTERNAL_TABLE_NAME
: il nome della tabella che vuoi creare, ad esempiomytable
SCHEMA
: lo schema per la tabella BigLake
Esempio:
bq mkdef --connection_id=myconnection --metadata_cache_mode=CACHE_MODE --source_format=CSV 'gs://mybucket/*.csv' > mytable_def bq mk --table --external_table_definition=mytable_def='gs://mybucket/*.csv' --max_staleness=0-0 0 4:0:0 myproject:mydataset.mybiglaketable Region:STRING,Quarter:STRING,Total_sales:INTEGER
Per utilizzare il rilevamento automatico degli schemi, imposta il flag --autodetect=true
nel comando mkdef
e ometti lo schema:
bq mkdef \ --connection_id=myconnection \ --metadata_cache_mode=CACHE_MODE \ --source_format=CSV --autodetect=true \ gs://mybucket/*.csv > mytable_def bq mk \ --table \ --external_table_definition=mytable_def=gs://mybucket/*.csv \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable
Opzione 2: definizione della tabella in linea
Anziché creare un file di definizione della tabella, puoi passare la definizione
della tabella direttamente al comando bq mk
.
Utilizza il decorator @connection
per specificare la connessione da utilizzare alla fine del flag --external_table_definition
.
bq mk --table \ --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \ DATASET_NAME.TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato dell'origine dati esternaAd esempio,
CSV
.BUCKET_PATH
: il percorso del bucket Cloud Storage che contiene i dati per la tabella, nel formatogs://bucket_name/[folder_name/]file_pattern
.Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (
*
) infile_pattern
. Ad esempio:gs://mybucket/file00*.parquet
. Per ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi.I seguenti esempi mostrano valori
uris
validi:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Quando specifichi valori
uris
che hanno come target più file, tutti questi file devono condividere uno schema compatibile.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso risorsa di Cloud Storage.
PROJECT_ID
: il nome del progetto in cui vuoi creare la tabella, ad esempiomyproject
REGION
: la regione che contiene la connessione,us
CONNECTION_ID
: l'ID connessione, ad esempiomyconnection
Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
.DATASET_NAME
: nome del set di dati in cui vuoi creare la tabella BigLakeTABLE_NAME
: il nome della tabella BigLakeSCHEMA
: lo schema per la tabella BigLake
Esempio:
bq mk --table \ --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable \ Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
Chiama il metodo API del metodo tables.insert
e crea un ExternalDataConfiguration
nella risorsa Table
che passi.
Specifica la proprietà schema
o imposta la proprietà autodetect
su true
per attivare il rilevamento automatico degli schemi per le origini dati supportate.
Specifica la proprietà connectionId
per identificare la connessione da utilizzare
per la connessione a Cloud Storage.
Terraform
In questo esempio viene creata una tabella BigLake sui dati non partizionati.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle sezioni seguenti.
prepara Cloud Shell
- Avvia Cloud Shell.
-
Imposta il progetto Google Cloud predefinito a 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
Se imposti valori espliciti nel file di configurazione Terraform, le variabili di ambiente vengono sostituite.
Prepara la directory
Ogni file di configurazione Terraform deve avere una propria directory (detta anche modulo principale).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome del file deve avere l'estensione
.tf
, ad esempiomain.tf
. In questo tutorial, il file è indicato comemain.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 file
main.tf
appena creato.Se vuoi, copia il codice da GitHub. Questa opzione è consigliata se lo snippet Terraform fa parte di una soluzione end-to-end.
- Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
- Salva le modifiche.
-
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
terraform init
Facoltativamente, per utilizzare la versione più recente 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 Terraform eseguendo il comando seguente e inserendo
yes
al prompt:terraform apply
Attendi finché Terraform non visualizza il messaggio "Applicazione completata".
- Apri il 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.
BigLake supporta il rilevamento automatico dello schema. Tuttavia, se non hai fornito uno schema e nei passaggi precedenti non è stato concesso l'accesso all'account di servizio, questi passaggi non andranno a buon fine e verrà visualizzato un messaggio di accesso negato se tenti di rilevare automaticamente lo schema.
Crea tabelle BigLake su dati partizionati Hive
Puoi creare una tabella BigLake per i dati partizionati Hive in Cloud Storage. Dopo aver creato una tabella partizionata esternamente, non puoi modificare la chiave di partizione. Devi ricreare la tabella per modificare la chiave di partizione.
Per creare una tabella BigLake basata su dati partizionati Hive in Cloud Storage, seleziona una delle seguenti opzioni:
Console
Vai alla pagina BigQuery.
Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
Fai clic su
Visualizza azioni e poi su Crea tabella. Viene visualizzato il riquadro Crea tabella.Nella sezione Origine, specifica i seguenti dettagli:
In Crea tabella da, seleziona Google Cloud Storage.
Specifica il percorso della cartella utilizzando caratteri jolly. Ad esempio,
my_bucket/my_files*
. La cartella deve trovarsi nella stessa posizione del set di dati contenente la tabella che vuoi creare, aggiungere o sovrascrivere.Nell'elenco Formato file, seleziona il tipo di file.
Seleziona la casella di controllo Partizionamento dei dati di origine e specifica i seguenti dettagli:
- In Seleziona prefisso URI di origine, inserisci il prefisso URI. Ad esempio,
gs://my_bucket/my_files
. - (Facoltativo) Per richiedere un filtro di partizionamento su tutte le query per questa tabella, seleziona la casella di controllo Richiedi filtro di partizionamento. La richiesta di un filtro di partizionamento può ridurre i costi e migliorare le prestazioni. Per maggiori informazioni, consulta Richiedere filtri dei predicati sulle chiavi di partizione nelle query.
Nella sezione Modalità di inferenza partizione, seleziona una delle seguenti opzioni:
- Deduci automaticamente i tipi: imposta la modalità di rilevamento dello schema di partizione su
AUTO
. - Tutte le colonne sono stringhe: imposta la modalità di rilevamento dello schema di partizione su
STRINGS
. - Fornisci un'opzione personalizzata: imposta la modalità di rilevamento dello schema di partizione su
CUSTOM
e inserisci manualmente le informazioni sullo schema per le chiavi di partizione. Per maggiori informazioni, consulta Fornire uno schema di chiavi di partizione personalizzato.
- Deduci automaticamente i tipi: imposta la modalità di rilevamento dello schema di partizione su
- In Seleziona prefisso URI di origine, inserisci il prefisso URI. Ad esempio,
Nella sezione Destinazione, specifica i seguenti dettagli:
- In Progetto, seleziona il progetto in cui vuoi creare la tabella.
- In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- In Tabella, inserisci il nome della tabella che vuoi creare.
- Per Tipo di tabella, seleziona Tabella esterna.
- Seleziona la casella di controllo Crea una tabella BigLake utilizzando una connessione a una risorsa cloud.
- Per ID connessione, seleziona la connessione creata in precedenza.
Nella sezione Schema, puoi abilitare il rilevamento automatico dello schema o specificare manualmente uno schema se disponi di un file di origine. Se non hai un file di origine, devi specificare manualmente uno schema.
Per attivare il rilevamento automatico dello schema, seleziona l'opzione Rilevamento automatico.
Per specificare manualmente uno schema, lascia deselezionata l'opzione Rilevamento automatico. Abilita Modifica come testo e inserisci lo schema della tabella come array JSON.
Per ignorare le righe con valori di colonna aggiuntivi che non corrispondono allo schema, espandi la sezione Opzioni avanzate e seleziona Valori sconosciuti.
Fai clic su Crea tabella.
SQL
Utilizza l'istruzione DDL CREATE EXTERNAL TABLE
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor query, inserisci la seguente istruzione:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS ( PARTITION_COLUMN PARTITION_COLUMN_TYPE, ) WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID` OPTIONS ( hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX", uris=['FILE_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE', format ="TABLE_FORMAT" );
Sostituisci quanto segue:
PROJECT_ID
: il nome del progetto in cui vuoi creare la tabella, ad esempiomyproject
DATASET
: il nome del set di dati BigQuery in cui vuoi creare la tabella, ad esempiomydataset
EXTERNAL_TABLE_NAME
: il nome della tabella che vuoi creare, ad esempiomytable
PARTITION_COLUMN
: il nome della colonna di partizionamentoPARTITION_COLUMN_TYPE
: il tipo di colonna di partizionamentoREGION
: la regione che contiene la connessione, ad esempious
CONNECTION_ID
: l'ID connessione, ad esempiomyconnection
Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
.HIVE_PARTITION_URI_PREFIX
: prefisso hive per il partizionamento dell'URI, ad esempiogs://mybucket/
FILE_PATH
: percorso dell'origine dati per la tabella esterna che vuoi creare, ad esempiogs://mybucket/*.parquet
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e la frequenza di aggiornamento dei metadati memorizzati nella cache affinché l'operazione li utilizzi. Per maggiori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore letterale a intervalli compreso tra 30 minuti e 7 giorni. Ad esempio, specifica
INTERVAL 4 HOUR
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.Imposta
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.TABLE_FORMAT
: il formato della tabella che vuoi creare, ad esempioPARQUET
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
Esempi
L'esempio seguente crea una tabella BigLake con dati partizionati in cui:
- Lo schema viene rilevato automaticamente.
- L'intervallo di inattività della cache dei metadati per la tabella è di 1 giorno.
- La cache dei metadati si aggiorna automaticamente.
CREATE EXTERNAL TABLE `my_dataset.my_table` WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
L'esempio seguente crea una tabella BigLake con dati partizionati in cui:
- Lo schema è specificato.
- L'intervallo di inattività della cache dei metadati per la tabella è di 8 ore.
- La cache dei metadati deve essere aggiornata manualmente.
CREATE EXTERNAL TABLE `my_dataset.my_table` ( ProductId INTEGER, ProductName STRING, ProductType STRING ) WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 8 HOUR, metadata_cache_mode = 'MANUAL' );
bq
Innanzitutto, utilizza il comando bq mkdef
per creare un file di definizione di tabella:
bq mkdef \ --source_format=SOURCE_FORMAT \ --connection_id=REGION.CONNECTION_ID \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ --metadata_cache_mode=CACHE_MODE \ GCS_URIS > DEFINITION_FILE
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato dell'origine dati esterna. Ad esempio,CSV
.REGION
: la regione che contiene la connessione, ad esempious
.CONNECTION_ID
: l'ID connessione, ad esempiomyconnection
.Quando visualizza i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
.PARTITIONING_MODE
: la modalità di partizionamento Hive. Utilizza uno dei seguenti valori:AUTO
: rileva automaticamente i nomi e i tipi di chiavi.STRINGS
: converte automaticamente i nomi delle chiavi in stringhe.CUSTOM
: codifica lo schema della chiave nel prefisso dell'URI di origine.
GCS_URI_SHARED_PREFIX
: il prefisso dell'URI di origine.BOOLEAN
: specifica se richiedere un filtro predicato al momento della query. Questo flag è facoltativo. Il valore predefinito èfalse
.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Devi includere questo flag solo se prevedi di utilizzare il flag--max_staleness
nel comandobq mk
successivo per abilitare la memorizzazione nella cache dei metadati. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.Imposta
AUTOMATIC
per l'aggiornamento della cache dei metadati a un intervallo definito dal sistema, di solito compreso tra 30 e 60 minuti.Imposta il valore su
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi richiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.GCS_URIS
: il percorso della cartella Cloud Storage, utilizzando il formato con caratteri jolly.DEFINITION_FILE
: il percorso del file di definizione della tabella sulla macchina locale.
Se PARTITIONING_MODE
è CUSTOM
, includi lo schema della chiave di partizione nel prefisso dell'URI di origine utilizzando il seguente formato:
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...
Dopo aver creato il file di definizione della tabella, utilizza il comando bq mk
per creare la tabella BigLake:
bq mk --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ DATASET_NAME.TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
DEFINITION_FILE
: il percorso del file di definizione della tabella.STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e la quantità di metadati memorizzati nella cache affinché l'operazione li utilizzi. Se includi questo flag, devi aver specificato anche un valore per il flag--metadata_cache_mode
nel comandobq mkdef
precedente. Per ulteriori informazioni sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per attivare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni utilizzando il formato
Y-M D H:M:S
descritto nella documentazione sui tipi di datiINTERVAL
. Ad esempio, specifica0-0 0 4:0:0
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.DATASET_NAME
: il nome del set di dati che contiene la tabella.TABLE_NAME
: il nome della tabella che stai creando.SCHEMA
: specifica il percorso di un file di schema JSON oppure specifica lo schema nel modulofield:data_type,field:data_type,...
. Per utilizzare il rilevamento automatico dello schema, ometti questo argomento.
Esempi
L'esempio seguente utilizza la modalità di partizionamento Hive AUTO
e imposta anche la cache dei metadati in modo che abbia un intervallo di inattività di 12 ore e venga aggiornata automaticamente:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=AUTO \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
--metadata_cache_mode=AUTOMATIC \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
--max_staleness=0-0 0 12:0:0 \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
L'esempio seguente utilizza la modalità di partizionamento Hive STRING
:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=STRING \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
L'esempio seguente utilizza la modalità di partizionamento Hive CUSTOM
:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=CUSTOM \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
Per impostare il partizionamento Hive utilizzando l'API BigQuery, includi l'oggetto hivePartitioningOptions
nell'oggetto ExternalDataConfiguration
quando crei il file di definizione della tabella.
Per creare una tabella BigLake, devi anche specificare un valore per il campo connectionId
.
Se imposti il campo hivePartitioningOptions.mode
su CUSTOM
, devi
codificare lo schema della chiave di partizione nel
campo hivePartitioningOptions.sourceUriPrefix
come segue:
gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...
Per forzare l'utilizzo di un filtro predicato al momento della query, imposta il campo hivePartitioningOptions.requirePartitionFilter
su true
.
Terraform
In questo esempio viene creata una tabella BigLake sui dati partizionati.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle sezioni seguenti.
prepara Cloud Shell
- Avvia Cloud Shell.
-
Imposta il progetto Google Cloud predefinito a 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
Se imposti valori espliciti nel file di configurazione Terraform, le variabili di ambiente vengono sostituite.
Prepara la directory
Ogni file di configurazione Terraform deve avere una propria directory (detta anche modulo principale).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome del file deve avere l'estensione
.tf
, ad esempiomain.tf
. In questo tutorial, il file è indicato comemain.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 file
main.tf
appena creato.Se vuoi, copia il codice da GitHub. Questa opzione è consigliata se lo snippet Terraform fa parte di una soluzione end-to-end.
- Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
- Salva le modifiche.
-
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
terraform init
Facoltativamente, per utilizzare la versione più recente 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 Terraform eseguendo il comando seguente e inserendo
yes
al prompt:terraform apply
Attendi finché Terraform non visualizza il messaggio "Applicazione completata".
- Apri il 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.
Configura i criteri di controllo dell'accesso
Puoi utilizzare diversi metodi per controllare l'accesso alle tabelle BigLake:
Per indicazioni sulla configurazione della sicurezza a livello di colonna, consulta la guida alla sicurezza a livello di colonna.
Per istruzioni su come impostare il mascheramento dei dati, consulta la guida al mascheramento dei dati.
Per indicazioni sulla configurazione della sicurezza a livello di riga, consulta la guida alla sicurezza a livello di riga.
Ad esempio, supponiamo di voler limitare l'accesso alle righe per la tabella mytable
nel set di dati mydataset
:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | | JP | tablet | 300 | | UK | laptop | 200 | +---------+---------+-------+
Puoi creare un filtro a livello di riga per Kim (kim@example.com
) che limita
il suo accesso alle righe in cui country
è uguale a US
.
CREATE ROW ACCESS POLICY only_us_filter ON mydataset.mytable GRANT TO ('user:kim@example.com') FILTER USING (country = 'US');
Quindi, Kim esegue la seguente query:
SELECT * FROM projectid.mydataset.mytable;
L'output mostra solo le righe in cui country
è uguale a US
:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | +---------+---------+-------+
Esegui query sulle tabelle BigLake
Per maggiori informazioni, consulta Eseguire query sui dati di Cloud Storage nelle tabelle BigLake.
Aggiornamento tabelle BigLake
Puoi aggiornare le tabelle BigLake se necessario, ad esempio per modificarne la memorizzazione nella cache dei metadati. Per ottenere i dettagli della tabella, come il formato di origine e l'URI di origine, consulta Ottenere informazioni sulla tabella.
Puoi utilizzare la stessa procedura anche per eseguire l'upgrade delle tabelle esterne basate su Cloud Storage a quelle BigLake associando la tabella esterna a una connessione. Per maggiori informazioni, consulta Eseguire l'upgrade delle tabelle esterne alle tabelle BigLake.
Per aggiornare una tabella BigLake, seleziona una delle seguenti opzioni:
SQL
Utilizza l'istruzione DDL CREATE OR REPLACE EXTERNAL TABLE
per aggiornare una tabella:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor query, inserisci la seguente istruzione:
CREATE OR REPLACE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION `REGION.CONNECTION_ID` OPTIONS( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
Sostituisci quanto segue:
PROJECT_ID
: il nome del progetto che contiene la tabellaDATASET
: il nome del set di dati che contiene la tabellaEXTERNAL_TABLE_NAME
: il nome della tabellaREGION
: la regione che contiene la connessioneCONNECTION_ID
: il nome della connessione da utilizzareTABLE_FORMAT
: il formato utilizzato dalla tabellaNon puoi modificare questa impostazione durante l'aggiornamento della tabella.
BUCKET_PATH
: il percorso del bucket Cloud Storage che contiene i dati per la tabella esterna, nel formato['gs://bucket_name/[folder_name/]file_name']
.Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (
*
) nel percorso. Ad esempio,['gs://mybucket/file_name*']
. Per maggiori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi.I seguenti esempi mostrano valori
uris
validi:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
Quando specifichi valori
uris
che hanno come target più file, tutti questi file devono condividere uno schema compatibile.Per maggiori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa di Cloud Storage.
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizziPer maggiori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per migliorare le prestazioni.
Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore letterale a intervalli compreso tra 30 minuti e 7 giorni. Ad esempio, specifica
INTERVAL 4 HOUR
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmentePer saperne di più sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta la pagina relativa alla memorizzazione dei metadati per le prestazioni.
Imposta
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
bq
Utilizza i comandi bq mkdef
e
bq update
per aggiornare una tabella:
Genera una definizione della tabella esterna che descriva gli aspetti della tabella da modificare:
bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \ --source_format=TABLE_FORMAT \ --metadata_cache_mode=CACHE_MODE \ "BUCKET_PATH" > /tmp/DEFINITION_FILE
Sostituisci quanto segue:
PROJECT_ID
: il nome del progetto che contiene il collegamentoREGION
: la regione che contiene la connessioneCONNECTION_ID
: il nome della connessione da utilizzareTABLE_FORMAT
: il formato utilizzato dalla tabella. Non puoi modificare questa impostazione durante l'aggiornamento della tabella.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.Imposta il valore
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, di solito compreso tra 30 e 60 minuti.Imposta il valore
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione stabilita. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache.Devi impostare
CACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.BUCKET_PATH
: il percorso del bucket Cloud Storage contenente i dati per la tabella esterna, nel formatogs://bucket_name/[folder_name/]file_name
.Puoi limitare i file selezionati dal bucket specificando un carattere jolly asterisco (
*
) nel percorso. Ad esempio,gs://mybucket/file_name*
. Per ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi.I seguenti esempi mostrano valori
uris
validi:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.csv
gs://bucket/path1/*,gs://bucket/path2/file00*
Quando specifichi valori
uris
che hanno come target più file, tutti questi file devono condividere uno schema compatibile.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso risorsa di Cloud Storage.
DEFINITION_FILE
: il nome del file di definizione della tabella che stai creando.
Aggiorna la tabella utilizzando la nuova definizione della tabella esterna:
bq update --max_staleness=STALENESS_INTERVAL \ --external_table_definition=/tmp/DEFINITION_FILE \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
Sostituisci quanto segue:
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per ulteriori informazioni sulle considerazioni sulla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.
Per abilitare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni utilizzando il formato
Y-M D H:M:S
descritto nella documentazione sui tipi di datiINTERVAL
. Ad esempio, specifica0-0 0 4:0:0
per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se la tabella è stata aggiornata nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti, l'operazione recupera i metadati da Cloud Storage.DEFINITION_FILE
: nome del file di definizione della tabella che hai creato o aggiornato.PROJECT_ID
: il nome del progetto che contiene la tabellaDATASET
: il nome del set di dati contenente la tabellaEXTERNAL_TABLE_NAME
: il nome della tabella
Esempio
L'esempio seguente aggiorna mytable
per utilizzare i metadati memorizzati nella cache, a condizione che siano stati aggiornati nelle ultime 4,5 ore, e anche per aggiornare automaticamente i metadati memorizzati nella cache:
bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable
Dove enable_metadata.json
ha i seguenti contenuti:
{
"metadataCacheMode": "AUTOMATIC"
}
Audit logging
Per informazioni sul logging in BigQuery, consulta Introduzione al monitoraggio di BigQuery. Per scoprire di più sul logging in Google Cloud, consulta Cloud Logging.
Passaggi successivi
- Scopri di più su BigLake.
- Scopri di più su Cloud Storage.
- Scopri di più sull'esecuzione di query sui dati AWS.
- Scopri di più sull'esecuzione di query sui dati di Azure.