Creare tabelle esterne BigLake di Amazon S3
Questo documento descrive come creare una tabella BigLake di Amazon Simple Storage Service (Amazon S3). Una tabella BigLake ti consente di utilizzare la delega di accesso per eseguire query sui dati in Amazon S3. La delega dell'accesso scollega l'accesso alla tabella BigLake dall'accesso al datastore sottostante.
Per informazioni su come i dati fluiscono tra BigQuery e Amazon S3, consulta Flusso di dati durante l'esecuzione di query sui dati.
Prima di iniziare
Assicurati di disporre di una connessione per accedere ai dati di Amazon S3.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per creare una tabella esterna,
chiedi all'amministratore di concederti il ruolo IAM Amministratore BigQuery (roles/bigquery.admin
) per il tuo set di dati.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene le autorizzazioni necessarie per creare una tabella esterna. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:
Autorizzazioni obbligatorie
Per creare una tabella esterna sono necessarie le seguenti autorizzazioni:
-
bigquery.tables.create
-
bigquery.connections.delegate
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Crea un set di dati
Prima di creare una tabella esterna, devi creare un set di dati nella regione supportata. Seleziona una delle seguenti opzioni:Console
Vai alla pagina BigQuery.
- Nel riquadro Explorer, seleziona il progetto in cui vuoi creare il set di dati.
- Espandi l'opzione Visualizza azioni e fai clic su Crea set di dati.
- Nella pagina Crea set di dati, specifica i seguenti dettagli:
- In ID set di dati, inserisci un nome univoco per il set di dati.
- Per Località dei dati, scegli una regione supportata.
- (Facoltativo) Per eliminare automaticamente le tabelle, seleziona la casella di controllo Attiva scadenza della tabella e imposta la Durata massima predefinita della tabella in giorni. I dati in Amazon S3 non vengono eliminati alla scadenza della tabella.
- Se vuoi utilizzare le regole di confronto predefinite, espandi la sezione Opzioni avanzate e seleziona l'opzione Attiva regole di confronto predefinite.
- Fai clic su Crea set di dati.
SQL
Utilizza l'istruzione DDL CREATE SCHEMA
.
L'esempio seguente crea un set di dati nella regione aws-us-east-1
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'editor di query, inserisci la seguente istruzione:
CREATE SCHEMA mydataset OPTIONS ( location = 'aws-us-east-1');
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 utilizzando il comando bq mk
:
bq --location=LOCATION mk \ --dataset \ PROJECT_ID:DATASET_NAME
Il parametro --project_id
sostituisce il progetto predefinito.
Sostituisci quanto segue:
LOCATION
: la posizione del set di datiPer informazioni sulle regioni supportate, consulta Località. Dopo aver creato un set di dati, non puoi modificarne la posizione. Puoi impostare un valore predefinito per la località utilizzando il file
.bigqueryrc
.PROJECT_ID
: il tuo ID progettoDATASET_NAME
: il nome del set di dati che vuoi crearePer 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
.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Creare tabelle BigLake su dati non partizionati
Seleziona una delle seguenti opzioni:
Console
Vai alla pagina BigQuery.
Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
Nella sezione Informazioni set di dati, fai clic su
Crea tabella.Nella sezione Origine della pagina Crea tabella:
- Per Crea tabella da, seleziona Amazon S3.
- In Seleziona percorso S3, inserisci un URI che rimandi ai dati di Amazon S3 nel formato
s3://BUCKET_NAME/PATH
. SostituisciBUCKET_NAME
con il nome del bucket Amazon S3. la regione del bucket deve essere la stessa del set di dati. SostituisciPATH
con il percorso in cui vuoi scrivere il file esportato. Può contenere un carattere jolly*
. - Per Formato file, seleziona il formato dei dati in Amazon S3. I formati supportati sono AVRO, CSV, DELTA_LAKE, ICEBERG, JSONL, ORC e PARQUET.
Nella sezione Destinazione, specifica i seguenti dettagli:
- Per Set di dati, scegli il set di dati appropriato.
- Nel campo Table (Tabella), inserisci il nome della tabella.
- Verifica che Tipo di tabella sia impostato su Tabella esterna.
- Per ID connessione, scegli l'ID connessione appropriato dal menu a discesa. Per informazioni sulle connessioni, consulta Connessione ad Amazon S3.
Nella sezione Schema, puoi attivare il rilevamento automatico dello schema o specificare manualmente uno schema se disponi di un file di origine. Se non disponi di 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 l'opzione Rilevamento automatico non selezionata. Attiva Modifica come testo e inserisci lo schema della tabella come array JSON.
Fai clic su Crea tabella.
SQL
Per creare una tabella BigLake, utilizza l'istruzione CREATE EXTERNAL TABLE
con la clausola WITH CONNECTION
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'editor di query, inserisci la seguente istruzione:
CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME` OPTIONS ( format = "DATA_FORMAT", uris = ["S3_URI"], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE');
Sostituisci quanto segue:
DATASET_NAME
: il nome del set di dati che hai creatoTABLE_NAME
: il nome che vuoi assegnare a questa tabellaAWS_LOCATION
: una località AWS in Google Cloud (ad es. "aws-us-east-1")CONNECTION_NAME
: il nome della connessione che hai creatoDATA_FORMAT
: uno dei formati federati di BigQuery supportati (ad esempioAVRO
,CSV
,DELTA_LAKE
,ICEBERG
oPARQUET
(anteprima))S3_URI
: un URI che rimanda ai dati di Amazon S3 (ad es.s3://bucket/path
)STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati per poter essere utilizzati dall'operazione. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.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 letterale intervallo 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 sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti a questa data, l'operazione recupera i metadati da Amazon S3.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 il rendimento.Impostato su
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.Imposta
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione da te 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 query, consulta Eseguire una query interattiva.
Esempio:
CREATE EXTERNAL TABLE awsdataset.awstable WITH CONNECTION `aws-us-east-1.s3-read-connection` OPTIONS ( format="CSV", uris=["s3://s3-bucket/path/file.csv"], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
bq
Crea un file di definizione della tabella:
bq mkdef \ --source_format=DATA_FORMAT \ --connection_id=AWS_LOCATION.CONNECTION_NAME \ --metadata_cache_mode=CACHE_MODE \ S3_URI > table_def
Sostituisci quanto segue:
DATA_FORMAT
: uno dei formati federati BigQuery supportati (ad esempioAVRO
,CSV
,DELTA_LAKE
,ICEBERG
oPARQUET
).S3_URI
: un URI che rimanda ai dati di Amazon S3 (ad esempio,s3://bucket/path
).AWS_LOCATION
: una località AWS in Google Cloud (ad esempioaws-us-east-1
).CONNECTION_NAME
: il nome della connessione che hai creato.CACHE_MODE
: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Devi includere questo flag solo se prevedi di utilizzare anche il flag--max_staleness
nel comandobq mk
successivo per attivare 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 il rendimento.Imposta su
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.Imposta
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache. Devi impostareCACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.
A questo punto, crea la tabella BigLake:
bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME
Sostituisci quanto segue:
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati per consentirne l'utilizzo da parte dell'operazione. Per ulteriori informazioni sui fattori da prendere in considerazione per la memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.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 letterale intervallo 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 sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono meno recenti, l'operazione recupera i metadati da Amazon S3.DATASET_NAME
: il nome del set di dati che hai creato.TABLE_NAME
: il nome che vuoi assegnare a questa tabella.
Ad esempio, il seguente comando crea una nuova tabella BigLake, awsdataset.awstable
, che può eseguire query sui dati di Amazon S3 archiviati nel percorso s3://s3-bucket/path/file.csv
e ha una connessione di lettura nella posizione aws-us-east-1
:
bq mkdef \ --autodetect \ --source_format=CSV \ --connection_id=aws-us-east-1.s3-read-connection \ --metadata_cache_mode=AUTOMATIC \ s3://s3-bucket/path/file.csv > table_def bq mk --max_staleness=INTERVAL "1" HOUR \ --external_table_definition=table_def awsdataset.awstable
API
Chiama il metodo API 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 dello schema per le origini dati supportate.
Specifica la proprietà connectionId
per identificare la connessione da utilizzare per la connessione ad Amazon S3.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Creare tabelle BigLake su dati partizionati
Puoi creare una tabella BigLake per i dati partizionati di Hive in Amazon S3. Una volta creata una tabella partizionata esterne, non puoi modificare la chiave di partizione. Per modificare la chiave di partizione, devi ricreare la tabella.
Per creare una tabella BigLake in base ai dati partizionati di Hive, 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. Si aprirà il riquadro Crea tabella.Nella sezione Origine, specifica i seguenti dettagli:
Per Crea tabella da, seleziona Amazon S3.
Fornisci il percorso della cartella utilizzando caratteri jolly. Ad esempio,
s3://mybucket/*
.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 poi specifica i seguenti dettagli:
- In Seleziona il prefisso dell'URI di origine, inserisci il prefisso dell'URI. Ad esempio,
s3://mybucket/my_files
. - (Facoltativo) Per richiedere un filtro di partizione per tutte le query per questa tabella, seleziona la casella di controllo Richiedi filtro di partizione. Se il filtro di partizionamento è obbligatorio, i costi possono essere ridotti e le prestazioni migliorate. Per ulteriori informazioni, consulta Requisire filtri di predicato sulle chiavi di partizione nelle query.
Nella sezione Modalità di inferenza della partizione, seleziona una delle seguenti opzioni:
- Deduzione automatica dei tipi: imposta la modalità di rilevamento dello schema della partizione su
AUTO
. - Tutte le colonne sono stringhe: imposta la modalità di rilevamento dello schema della partizione su
STRINGS
. - Fornisci il mio: imposta la modalità di rilevamento dello schema della partizione su
CUSTOM
e inserisci manualmente le informazioni sullo schema per le chiavi di partizione. Per ulteriori informazioni, consulta Schema della chiave di partizione personalizzata.
- Deduzione automatica dei tipi: imposta la modalità di rilevamento dello schema della partizione su
- In Seleziona il prefisso dell'URI di origine, inserisci il prefisso dell'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.
- In Tipo di tabella, verifica che sia selezionata l'opzione Tabella esterna.
- Per ID connessione, seleziona la connessione che hai creato in precedenza.
Nella sezione Schema, puoi attivare il rilevamento automatico dello schema o specificare manualmente uno schema se disponi di un file di origine. Se non disponi di 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 l'opzione Rilevamento automatico non selezionata. Attiva 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 di 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'], format ="TABLE_FORMAT" 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
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
: il nome della connessione, ad esempiomyconnection
HIVE_PARTITION_URI_PREFIX
: prefisso dell'uri per la suddivisione in parti di Hive, ad esempios3://mybucket/
FILE_PATH
: percorso dell'origine dati per la tabella esterna che vuoi creare, ad esempio:s3://mybucket/*.parquet
TABLE_FORMAT
: il formato della tabella che vuoi creare, ad esempioPARQUET
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati per poter essere utilizzati dall'operazione. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.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 letterale intervallo 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 sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono precedenti a questa data, l'operazione recupera i metadati da Amazon S3.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 il rendimento.Impostato su
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.Imposta
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione da te 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 query, consulta Eseguire una query interattiva.
Esempi
L'esempio seguente crea una tabella BigLake su dati partizionati in Amazon S3. Lo schema viene rilevato automaticamente.
CREATE EXTERNAL TABLE `my_dataset.my_table` WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "s3://mybucket/products", uris = ['s3://mybucket/products/*'] max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
bq
Innanzitutto, utilizza il comando
bq mkdef
per
creare un file di definizione della tabella:
bq mkdef \ --source_format=SOURCE_FORMAT \ --connection_id=REGION.CONNECTION_ID \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ --metadata_cache_mode=CACHE_MODE \ URIS > DEFINITION_FILE
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato della fonte di dati esterna. Ad esempio,CSV
.REGION
: la regione che contiene la connessione, ad esempious
.CONNECTION_ID
: il nome della connessione, ad esempiomyconnection
.PARTITIONING_MODE
: la modalità di partizionamento Hive. Utilizza uno dei seguenti valori:AUTO
: rileva automaticamente i nomi e i tipi di chiavi.STRINGS
: converti automaticamente i nomi delle chiavi in stringhe.CUSTOM
: codifica lo schema della chiave nel prefisso dell'URI di origine.
URI_SHARED_PREFIX
: il prefisso dell'URI di origine.BOOLEAN
: specifica se è necessario 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 anche il flag--max_staleness
nel comandobq mk
successivo per attivare 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 il rendimento.Imposta su
AUTOMATIC
per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.Imposta
MANUAL
se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
per aggiornare la cache. Devi impostareCACHE_MODE
seSTALENESS_INTERVAL
è impostato su un valore maggiore di 0.URIS
: il percorso della cartella Amazon S3, utilizzando il formato carattere jolly.DEFINITION_FILE
: il percorso del file di definizione della tabella sulla tua 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=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 --max_staleness=STALENESS_INTERVAL \ --external_table_definition=DEFINITION_FILE \ DATASET_NAME.TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
STALENESS_INTERVAL
: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati per consentirne l'utilizzo da parte dell'operazione. Per ulteriori informazioni sui fattori da prendere in considerazione per la memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.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 letterale intervallo 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 sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Amazon S3.DEFINITION_FILE
: il percorso del file di definizione della tabella.DATASET_NAME
: il nome del set di dati che contiene la tabella.TABLE_NAME
: il nome della tabella che stai creando.SCHEMA
: specifica un percorso a un file dello schema JSON oppure specifica lo schema nel formatofield:data_type,field:data_type,...
. Per utilizzare il rilevamento automatico dello schema, ometti questo argomento.
Esempi
L'esempio seguente utilizza la AUTO
modalità di partizione Hive per i dati Amazon S3:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=AUTO \
--hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
--metadata_cache_mode=AUTOMATIC \
s3://mybucket/* > mytable_def
bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
L'esempio seguente utilizza la STRING
modalità di partizione Hive per i dati Amazon S3:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=STRING \
--hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
--metadata_cache_mode=AUTOMATIC \
s3://mybucket/myTable/* > mytable_def
bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
Per impostare la partizione 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:
s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...
Per applicare l'utilizzo di un filtro predicato al momento della query, imposta il campo hivePartitioningOptions.requirePartitionFilter
su true
.
Tabelle Delta Lake
Delta Lake è un formato di tabella open source che supporta tabelle di dati su scala petabyte. È possibile eseguire query sulle tabelle Delta Lake sia come tabelle temporanee che permanenti e sono supportate come tabelle BigLake.
Sincronizzazione dello schema
Delta Lake gestisce uno schema canonico come parte dei metadati. Non puoi aggiornare uno schema utilizzando un file di metadati JSON. Per aggiornare lo schema:
Utilizza il comando
bq update
con il flag--autodetect_schema
:bq update --autodetect_schema PROJECT_ID:DATASET.TABLE
Sostituisci quanto segue:
PROJECT_ID
: l'ID progetto contenente la tabella che vuoi aggiornareDATASET
: il set di dati contenente la tabella che vuoi aggiornareTABLE
: la tabella da aggiornare
Conversione dei tipi
BigQuery converte i tipi di dati di Delta Lake nei seguenti tipi di dati BigQuery:
Tipo di Lake Delta | Tipo BigQuery |
---|---|
boolean |
BOOL |
byte |
INT64 |
int |
INT64 |
long |
INT64 |
float |
FLOAT64 |
double |
FLOAT64 |
Decimal(P/S) |
NUMERIC o BIG_NUMERIC a seconda della precisione |
date |
DATE |
time |
TIME |
timestamp (not partition column) |
TIMESTAMP |
timestamp (partition column) |
DATETIME |
string |
STRING |
binary |
BYTES |
array<Type> |
ARRAY<Type> |
struct |
STRUCT |
map<KeyType, ValueType> |
ARRAY<Struct<key KeyType, value ValueType>> |
Limitazioni
Alle tabelle Delta Lake si applicano le seguenti limitazioni:
I limiti delle tabelle esterne si applicano alle tabelle Delta Lake.
Le tabelle Delta Lake sono supportate solo su BigQuery Omni e presentano le limitazioni associate.
Non puoi aggiornare una tabella con un nuovo file JSON con i metadati. Devi utilizzare un'operazione di aggiornamento della tabella dello schema con rilevamento automatico. Per ulteriori informazioni, consulta la sezione Sincronizzazione dello schema.
Le funzionalità di sicurezza di BigLake proteggono le tabelle Delta Lake solo quando si accede tramite i servizi BigQuery.
Crea una tabella Delta Lake
L'esempio seguente crea una tabella esterna utilizzando l'istruzione CREATE EXTERNAL
TABLE
con il formato Delta Lake:
CREATE [OR REPLACE] EXTERNAL TABLE table_name WITH CONNECTION connection_name OPTIONS ( format = 'DELTA_LAKE', uris = ["parent_directory"] );
Sostituisci quanto segue:
table_name: il nome della tabella.
connection_name: il nome della connessione. La connessione deve identificare un'origine Amazon S3 o Blob Storage.
parent_directory: l'URI della directory principale.
Trasferimento cross-cloud con Delta Lake
L'esempio seguente utilizza l'istruzione LOAD DATA
per caricare i dati nella tabella appropriata:
LOAD DATA [INTO | OVERWRITE] table_name FROM FILES ( format = 'DELTA_LAKE', uris = ["parent_directory"] ) WITH CONNECTION connection_name;
Per altri esempi di trasferimenti di dati cross-cloud, vedi Caricare i dati con operazioni cross-cloud.
Esegui query sulle tabelle BigLake
Per ulteriori informazioni, consulta Eseguire query sui dati di Amazon S3.
Visualizzare i metadati delle risorse
Puoi visualizzare i metadati delle risorse con le visualizzazioniINFORMATION_SCHEMA
. Quando esegui query sulle visualizzazioni
JOBS_BY_*
,
JOBS_TIMELINE_BY_*
e
RESERVATION*
,
devi specificare la posizione di elaborazione della query
che si trova nella regione della tabella. Per informazioni sulle località di BigQuery Omni, consulta Località. Per tutte le altre tabelle di sistema, la specifica della posizione del job di query è facoltativa.
Per informazioni sulle tabelle di sistema supportate da BigQuery Omni, consulta Limitazioni.
Per eseguire query sulle tabelle di sistema JOBS_*
e RESERVATION*
, seleziona uno dei seguenti metodi per specificare la posizione di elaborazione:
Console
Vai alla pagina BigQuery.
Se la scheda Editor non è visibile, fai clic su
Crea nuova query.Fai clic su Altro > Impostazioni query. Viene visualizzata la finestra di dialogo Impostazioni query.
Nella finestra di dialogo Impostazioni query, in Impostazioni aggiuntive > Posizione dei dati, seleziona la regione BigQuery collocata con la regione BigQuery Omni. Ad esempio, se la regione BigQuery Omni è
aws-us-east-1
, specificaus-east4
.Seleziona i campi rimanenti e fai clic su Salva.
bq
Utilizza il flag --location
per impostare la località di elaborazione del job sulla
regione BigQuery collocata insieme alla regione BigQuery Omni.
Ad esempio, se la regione BigQuery Omni è aws-us-east-1
,
specifica us-east4
.
Esempio
bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"
bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"
API
Se esegui i job in modo programmatico, imposta l'argomento location sulla regione BigQuery collocata nella regione BigQuery Omni.
Ad esempio, se la regione BigQuery Omni è aws-us-east-1
,
specifica us-east4
.
L'esempio seguente elenca i job di aggiornamento dei metadati:
SELECT * FROM `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT` WHERE job_id LIKE '%metadata_cache_refresh%' AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR) ORDER BY start_time desc LIMIT 10;
Controlli di servizio VPC
Puoi utilizzare i perimetri Controlli di servizio VPC per limitare l'accesso da BigQuery Omni a un servizio cloud esterno come un livello aggiuntivo di difesa. Ad esempio, i perimetri dei Controlli di servizio VPC possono limitare le esportazioni dalle tue tabelle BigQuery Omni a un bucket Amazon S3 o a un contenitore di Archiviazione BLOB specifico.
Per scoprire di più sui Controlli di servizio VPC, consulta Panoramica dei Controlli di servizio VPC.
Autorizzazione obbligatoria
Assicurati di disporre delle autorizzazioni necessarie per configurare i perimetri di servizio. Per visualizzare un elenco dei ruoli IAM necessari per configurare i Controlli di servizio VPC, consulta Controllo dell'accesso con IAM nella documentazione dei Controlli di servizio VPC.
Configurare i Controlli di servizio VPC utilizzando la console Google Cloud
Nel menu di navigazione della console Google Cloud, fai clic su Sicurezza, quindi su Controlli di servizio VPC.
Per configurare Controlli di servizio VPC per BigQuery Omni, segui la procedura descritta nella guida Creare un perimetro di servizio e, quando sei nel riquadro Regole di uscita, segui questi passaggi:
Nel riquadro Regole in uscita, fai clic su Aggiungi regola.
Nella sezione Attributi FROM del client API, seleziona un'opzione dall'elenco Identità.
Seleziona Attributi TO delle risorse esterne.
Per aggiungere una risorsa esterna, fai clic su Aggiungi risorse esterne.
Nella finestra di dialogo Aggiungi risorsa esterna, in Nome risorsa esterna, inserisci un nome risorsa valido. Ad esempio:
Per Amazon Simple Storage Service (Amazon S3):
s3://BUCKET_NAME
Sostituisci BUCKET_NAME con il nome del tuo bucket Amazon S3.
Per Azure Blob Storage:
azure://myaccount.blob.core.windows.net/CONTAINER_NAME
Sostituisci CONTAINER NAME con il nome del tuo container Blob Storage.
Per un elenco degli attributi delle regole di uscita, consulta la sezione Riferimento alle regole di uscita.
Seleziona i metodi che vuoi consentire nelle risorse esterne:
- Se vuoi consentire tutti i metodi, seleziona Tutti i metodi nell'elenco Metodi.
- Se vuoi consentire metodi specifici, seleziona Metodo selezionato, fai clic su Seleziona metodi e poi seleziona i metodi che vuoi consentire nelle risorse esterne.
Fai clic su Crea perimetro.
Configurare i Controlli di servizio VPC utilizzando gcloud CLI
Per configurare i Controlli di servizio VPC utilizzando gcloud CLI, segui questi passaggi:
- Imposta il criterio di accesso predefinito.
- Crea il file di input del criterio in uscita.
- Aggiungi il criterio di uscita.
Impostare il criterio di accesso predefinito
Un criterio di accesso è un contenitore per l'intera organizzazione per i livelli di accesso e i perimetri di servizio. Per informazioni su come impostare un criterio di accesso predefinito o ottenere il nome di un criterio di accesso, consulta Gestire un criterio di accesso.
Crea il file di input del criterio in uscita
Un blocco di regole in uscita definisce l'accesso consentito dall'interno di un perimetro alle risorse al di fuori di quel perimetro. Per le risorse esterne, la proprietà externalResources
definisce i percorsi delle risorse esterne a cui è consentito l'accesso dall'interno del perimetro di Controlli di servizio VPC.
Le regole di uscita possono essere configurate utilizzando un file JSON o un file YAML. L'esempio seguente utilizza il formato .yaml
:
- egressTo: operations: - serviceName: bigquery.googleapis.com methodSelectors: - method: "*" *OR* - permission: "externalResource.read" externalResources: - EXTERNAL_RESOURCE_PATH egressFrom: identityType: IDENTITY_TYPE *OR* identities: - serviceAccount:SERVICE_ACCOUNT
egressTo
: elenca le operazioni di servizio consentite sulle risorse Google Cloud in progetti specificati al di fuori del perimetro.operations
: elenca i servizi e le azioni o i metodi accessibili a cui un client che soddisfa le condizioni di bloccofrom
è autorizzato ad accedere.serviceName
: impostabigquery.googleapis.com
per BigQuery Omni.methodSelectors
: elenca i metodi a cui può accedere un client che soddisfa le condizionifrom
. Per i metodi e le autorizzazioni limitabili per i servizi, consulta Limitazioni del metodo dei servizi supportati.method
: un metodo di servizio valido oppure\"*\"
per consentire tutti i metodiserviceName
.permission
: un'autorizzazione di servizio valida, ad esempio\"*\"
,externalResource.read
oexternalResource.write
. L'accesso alle risorse al di fuori del perimetro è consentito per le operazioni che richiedono questa autorizzazione.externalResources
: elenca le risorse esterne a cui possono accedere i client all'interno di un perimetro. Sostituisci EXTERNAL_RESOURCE_PATH con un bucket Amazon S3 valido, ad esempios3://bucket_name
, o con un percorso del contenitore Blob Storage, ad esempioazure://myaccount.blob.core.windows.net/container_name
.egressFrom
: elenca le operazioni di servizio consentite sulle risorse Google Cloud in progetti specifici all'interno del perimetro.identityType
oidentities
: definisce i tipi di identità che possono accedere alle risorse specificate al di fuori del perimetro. Sostituisci IDENTITY_TYPE con uno dei seguenti valori validi:ANY_IDENTITY
: per consentire tutte le identità.ANY_USER_ACCOUNT
: per consentire a tutti gli utenti.ANY_SERVICE_ACCOUNT
: per consentire tutti gli account di servizio
identities
: elenca gli account di servizio che possono accedere alle risorse specificate al di fuori del perimetro.serviceAccount
(facoltativo): sostituisci SERVICE_ACCOUNT con l'account di servizio che può accedere alle risorse specificate al di fuori del perimetro.
Esempi
Il seguente esempio è un criterio che consente le operazioni in uscita dall'interno del perimetro alla posizione Amazon S3 s3://mybucket
in AWS.
- egressTo: operations: - serviceName: bigquery.googleapis.com methodSelectors: - method: "*" externalResources: - s3://mybucket - s3://mybucket2 egressFrom: identityType: ANY_IDENTITY
L'esempio seguente consente le operazioni in uscita in un contenitore Blob Storage:
- egressTo: operations: - serviceName: bigquery.googleapis.com methodSelectors: - method: "*" externalResources: - azure://myaccount.blob.core.windows.net/mycontainer egressFrom: identityType: ANY_IDENTITY
Per ulteriori informazioni sui criteri di uscita, consulta la pagina Informazioni di riferimento sulle regole di uscita.
Aggiungi il criterio di uscita
Per aggiungere il criterio di uscita quando crei un nuovo perimetro di servizio, utilizza il
comando gcloud access-context-manager perimeters create
.
Ad esempio, il seguente comando crea un nuovo perimetro denominato omniPerimeter
che include il progetto con il numero 12345
, limita l'API BigQuery e aggiunge un criterio di uscita definito nel file egress.yaml
:
gcloud access-context-manager perimeters create omniPerimeter \ --title="Omni Perimeter" \ --resources=projects/12345 \ --restricted-services=bigquery.googleapis.com \ --egress-policies=egress.yaml
Per aggiungere il criterio di uscita a un perimetro di servizio esistente, utilizza il
comando gcloud access-context-manager perimeters update
.
Ad esempio, il seguente comando aggiunge un criterio di uscita definito nel
egress.yaml
file a un perimetro di servizio esistente denominato omniPerimeter
:
gcloud access-context-manager perimeters update omniPerimeter --set-egress-policies=egress.yaml
Verifica il perimetro
Per verificare il perimetro, utilizza il
comando gcloud access-context-manager perimeters describe
:
gcloud access-context-manager perimeters describe PERIMETER_NAME
Sostituisci PERIMETER_NAME con il nome del perimetro.
Ad esempio, il seguente comando descrive il perimetro omniPerimeter
:
gcloud access-context-manager perimeters describe omniPerimeter
Per saperne di più, consulta Gestire i perimetri di servizio.
Consenti l'accesso della VPC di BigQuery Omni ad Amazon S3
Per richiedere feedback o assistenza per questa funzionalità, invia un'email all'indirizzo bq-omni-customer-support@google.com.
In qualità di amministratore di BigQuery, puoi creare un criterio per i bucket S3 per grantare a BigQuery Omni l'accesso alle tue risorse Amazon S3. In questo modo, solo le VPC BigQuery Omni autorizzate possono interagire con il tuo Amazon S3, migliorando la sicurezza dei tuoi dati.
Applica un criterio del bucket S3 per la VPC BigQuery Omni
Per applicare un criterio del bucket S3, utilizza l'interfaccia a riga di comando AWS o Terraform:
Interfaccia a riga di comando AWS
Esegui il comando seguente per applicare un criterio del bucket S3 che include una condizione che utilizza l'attributo aws:SourceVpc
:
aws s3api put-bucket-policy \ --bucket=BUCKET_NAME \ --policy "{ \"Version\": \"2012-10-17\", \"Id\": \"RestrictBucketReads\", \"Statement\": [ { \"Sid\": \"AccessOnlyToOmniVPC\", \"Principal\": \"*\", \"Action\": [\"s3:ListBucket\", \"s3:GetObject\"], \"Effect\": \"Allow\", \"Resource\": [\"arn:aws:s3:::BUCKET_NAME\", \"arn:aws:s3:::BUCKET_NAME/*\"], \"Condition\": { \"StringEquals\": { \"aws:SourceVpc\": \"VPC_ID\" } } } ] }"
Sostituisci quanto segue:
BUCKET_NAME
: il bucket Amazon S3 a cui vuoi che BigQuery acceda.VPC_ID
: l'ID VPC BigQuery Omni della regione BigQuery Omni collocata con il bucket Amazon S3. Puoi trovare queste informazioni nella tabella di questa pagina.
Terraform
Aggiungi quanto segue al file di configurazione Terraform:
resource "aws_s3_bucket" "example" { bucket = "BUCKET_NAME" } resource "aws_s3_bucket_policy" "example" { bucket = aws_s3_bucket.example.id policy = jsonencode({ Version = "2012-10-17" Id = "RestrictBucketReads" Statement = [ { Sid = "AccessOnlyToOmniVPC" Effect = "Allow" Principal = "*" Action = ["s3:GetObject", "s3:ListBucket"] Resource = [ aws_s3_bucket.example.arn, "${aws_s3_bucket.example.arn}/*" ] Condition = { StringEquals = { "aws:SourceVpc": "VPC_ID" } } }, ] }) }
Sostituisci quanto segue:
BUCKET_NAME
: il bucket Amazon S3 a cui vuoi che BigQuery acceda.VPC_ID
: l'ID VPC BigQuery Omni della regione BigQuery Omni collocata con il bucket Amazon S3.
ID risorse VPC BigQuery Omni
Regione | ID VPC |
---|---|
aws-ap-northeast-2 | vpc-0b488548024288af2 |
aws-ap-southeast-2 | vpc-0726e08afef3667ca |
aws-eu-central-1 | vpc-05c7bba12ad45558f |
aws-eu-west-1 | vpc-0e5c646979bbe73a0 |
aws-us-east-1 | vpc-0bf63a2e71287dace |
aws-us-west-2 | vpc-0cc24e567b9d2c1cb |
Limitazioni
Per un elenco completo delle limitazioni che si applicano alle tabelle BigLake basate su Amazon S3 e Blob Storage, consulta Limitazioni.
Passaggi successivi
- Scopri di più su BigQuery Omni.
- Utilizza il lab BigQuery Omni con AWS.
- Scopri di più sulle tabelle BigLake.
- Scopri come esportare i risultati di query in Amazon S3.
- Scopri come creare visualizzazioni materializzate nelle tabelle con cache dei metadati di Amazon Simple Storage Service (Amazon S3).
- Scopri come rendere disponibili localmente i dati di Amazon S3 in una vista materializzata per le unioni creando una replica della vista materializzata.