Creazione di tabelle esterne Cloud Storage
BigQuery supporta l'esecuzione di query sui dati di Cloud Storage nei seguenti formati:
- Valori separati da virgola (CSV)
- JSON (delimitato da nuova riga)
- Avro
- ORC
- Parquet
- Esportazioni di Datastore
- Esportazioni di Firestore
BigQuery supporta l'esecuzione di query sui dati di Cloud Storage da queste classi di archiviazione:
- Standard
- Nearline
- Coldline
- Archive
Per eseguire query su una tabella esterna di Cloud Storage, devi disporre delle autorizzazioni sia per la tabella esterna che per i file di Cloud Storage. Se possibile, ti consigliamo di utilizzare una tabella BigLake. Le tabelle BigLake forniscono la delega di accesso, pertanto devi disporre delle autorizzazioni solo per la tabella BigLake per eseguire query sui dati di Cloud Storage.
Assicurati di considerare la località del set di dati e del bucket Cloud Storage quando esegui query sui dati archiviati in Cloud Storage.
Prima di iniziare
Concedi i ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività nel documento. Le eventuali autorizzazioni necessarie per eseguire un'attività sono elencate nella sezione "Autorizzazioni richieste" dell'attività.
Ruoli obbligatori
Per creare una tabella esterna, devi disporre dell'autorizzazione bigquery.tables.create
BigQuery Identity and Access Management (IAM).
Ciascuno dei seguenti ruoli predefiniti di Identity and Access Management include questa autorizzazione:
- Editor dati BigQuery (
roles/bigquery.dataEditor
) - Proprietario dati BigQuery (
roles/bigquery.dataOwner
) - Amministratore BigQuery (
roles/bigquery.admin
)
Devi inoltre disporre delle autorizzazioni seguenti per accedere al bucket Cloud Storage contenente i tuoi dati:
storage.buckets.get
storage.objects.get
storage.objects.list
(obbligatorio se utilizzi un caratteri jolly nell'URI)
Il ruolo predefinito Identity and Access Management di Cloud Storage Storage (roles/storage.admin
) include queste autorizzazioni.
Se non sei un'entità in uno di questi ruoli, chiedi all'amministratore di concederti l'accesso o di creare la tabella esterna per te.
Per ulteriori informazioni sui ruoli e sulle autorizzazioni di Identity and Access Management in BigQuery, consulta Ruoli e autorizzazioni predefiniti.
Ambiti di accesso per le istanze di Compute Engine
Se da un'istanza Compute Engine devi eseguire una query su una tabella esterna collegata a un'origine Cloud Storage, l'istanza deve avere almeno l'ambito di accesso in sola lettura di Cloud Storage (https://www.googleapis.com/auth/devstorage.read_only
).
Gli ambiti controllano l'accesso dell'istanza Compute Engine ai prodotti Google Cloud, tra cui Cloud Storage. Le applicazioni in esecuzione sull'istanza utilizzano l'account di servizio associato all'istanza per chiamare le API Google Cloud.
Se configuri un'istanza Compute Engine per l'esecuzione come account di servizio Compute Engine predefinito, per impostazione predefinita all'istanza viene concesso un numero di ambiti predefiniti, tra cui l'ambito https://www.googleapis.com/auth/devstorage.read_only
.
Se invece configuri l'istanza con un account di servizio personalizzato, assicurati di concedere esplicitamente l'ambito https://www.googleapis.com/auth/devstorage.read_only
all'istanza.
Per informazioni sull'applicazione degli ambiti a un'istanza di Compute Engine, consulta Modifica dell'account di servizio e degli ambiti di accesso per un'istanza. Per ulteriori informazioni sugli account di servizio Compute Engine, consulta Account di servizio.
Creare tabelle esterne su dati non partizionati
Puoi creare una tabella permanente collegata all'origine dati esterna:
- Utilizzo della console Google Cloud
- Utilizzo del comando
bq mk
- Creazione di un elemento
ExternalDataConfiguration
quando utilizzi il metodo APItables.insert
- È in esecuzione l'istruzione
CREATE EXTERNAL TABLE
(Data Definition Language). - Utilizzo delle librerie client
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.
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
Puoi creare una tabella esterna permanente eseguendo 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` OPTIONS ( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'[,...]] );
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
TABLE_FORMAT
: il formato della tabella che vuoi creare, ad esempioPARQUET
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.
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
Esempi
L'esempio seguente utilizza il rilevamento automatico dello schema per creare una tabella esterna denominata sales
collegata a un file CSV archiviato in Cloud Storage:
CREATE OR REPLACE EXTERNAL TABLE mydataset.sales OPTIONS ( format = 'CSV', uris = ['gs://mybucket/sales.csv']);
L'esempio successivo specifica uno schema in modo esplicito e ignora la prima riga del file CSV:
CREATE OR REPLACE EXTERNAL TABLE mydataset.sales ( Region STRING, Quarter STRING, Total_Sales INT64 ) OPTIONS ( format = 'CSV', uris = ['gs://mybucket/sales.csv'], skip_leading_rows = 1);
bq
Per creare una tabella esterna, utilizza il comando bq mk
con il flag --external_table_definition
. Questo flag contiene un percorso a un file di definizione della tabella o una definizione di tabella in linea.
Opzione 1: file di definizione tabella
Utilizza il comando bq mkdef
per creare un file di definizione della tabella, quindi trasmetti il percorso del file al comando bq mk
come segue:
bq mkdef --source_format=SOURCE_FORMAT \ BUCKET_PATH > DEFINITION_FILE bq mk --table \ --external_table_definition=DEFINITION_FILE \ DATASET_NAME.TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato dell'origine dati esterna. Ad 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.
DEFINITION_FILE
: il percorso del file di definizione della tabella sulla macchina locale.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,...
.
Esempio:
bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable \
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 --source_format=CSV --autodetect=true \
gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable
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
:
bq mk --table \ --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH \ 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.
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.
Esempio:
bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
mydataset.mytable \
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.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Creare tabelle esterne su dati partizionati
Puoi creare una tabella esterna per i dati partizionati di Hive che risiedono 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 esterna per i dati partizionati Hive, scegli una delle seguenti opzioni:
Console
Nella console Google Cloud, vai a 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.
- In Seleziona file dal bucket Cloud Storage, inserisci il percorso della cartella Cloud Storage utilizzando i caratteri jolly.
Ad esempio:
my_bucket/my_files*
. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella da creare, aggiungere o sovrascrivere. - Nell'elenco Formato file, seleziona il tipo di file.
- Seleziona la casella di controllo Partizionamento dei dati di origine e, per Seleziona
prefisso dell'URI di origine, inserisci il prefisso dell'URI Cloud Storage. Ad esempio,
gs://my_bucket/my_files
. - Nella sezione Modalità di inferenza delle partizioni, 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 partizionamento personalizzato.
- Deduci automaticamente i tipi: imposta la modalità di rilevamento dello schema di partizione su
- (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 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.
- Nella sezione Schema, inserisci la definizione di schema.
- Per attivare il rilevamento automatico dello schema, seleziona Rilevamento automatico.
- 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
.
L'esempio seguente utilizza il rilevamento automatico delle chiavi di partizione Hive:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS OPTIONS ( format = 'SOURCE_FORMAT', uris = ['GCS_URIS'], hive_partition_uri_prefix = 'GCS_URI_SHARED_PREFIX', require_hive_partition_filter = BOOLEAN);
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato dell'origine dati esterna, ad esempioPARQUET
GCS_URIS
: percorso della cartella Cloud Storage, in formato con caratteri jollyGCS_URI_SHARED_PREFIX
: il prefisso dell'URI di origine senza il carattere jollyBOOLEAN
: se richiedere un filtro predicato al momento della query. Questo flag è facoltativo. Il valore predefinito èfalse
.
L'esempio seguente utilizza chiavi e tipi di partizione Hive personalizzate elencandoli nella clausola WITH PARTITION COLUMNS
:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS (PARTITION_COLUMN_LIST) OPTIONS ( format = 'SOURCE_FORMAT', uris = ['GCS_URIS'], hive_partition_uri_prefix = 'GCS_URI_SHARED_PREFIX', require_hive_partition_filter = BOOLEAN);
Sostituisci quanto segue:
PARTITION_COLUMN_LIST
: un elenco di colonne che segue lo stesso ordine nel percorso della cartella Cloud Storage, nel formato:
KEY1 TYPE1, KEY2 TYPE2
L'esempio seguente crea una tabella partizionata esternamente. Utilizza il rilevamento automatico dello schema per rilevare sia lo schema file sia il layout di partizionamento hive. Se il percorso esterno è gs://bucket/path/field_1=first/field_2=1/data.parquet
, le colonne di partizione vengono rilevate come field_1
(STRING
) e field_2
(INT64
).
CREATE EXTERNAL TABLE dataset.AutoHivePartitionedTable WITH PARTITION COLUMNS OPTIONS ( uris = ['gs://bucket/path/*'], format = 'PARQUET', hive_partition_uri_prefix = 'gs://bucket/path', require_hive_partition_filter = false);
L'esempio seguente crea una tabella partizionata esternamente specificando le colonne di partizione in modo esplicito. Questo esempio presuppone che il percorso del file esterno abbia il pattern gs://bucket/path/field_1=first/field_2=1/data.parquet
.
CREATE EXTERNAL TABLE dataset.CustomHivePartitionedTable WITH PARTITION COLUMNS ( field_1 STRING, -- column order must match the external path field_2 INT64) OPTIONS ( uris = ['gs://bucket/path/*'], format = 'PARQUET', hive_partition_uri_prefix = 'gs://bucket/path', require_hive_partition_filter = false);
bq
Innanzitutto, utilizza il comando bq mkdef
per creare un file di definizione di tabella:
bq mkdef \ --source_format=SOURCE_FORMAT \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ GCS_URIS > DEFINITION_FILE
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato dell'origine dati esterna. Ad esempio,CSV
.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
.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 esterna:
bq mk --external_table_definition=DEFINITION_FILE \ DATASET_NAME.TABLE_NAME \ SCHEMA
Sostituisci quanto segue:
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 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
:
bq mkdef --source_format=CSV \
--hive_partitioning_mode=AUTO \
--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 STRING
:
bq mkdef --source_format=CSV \
--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 \
--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 un oggetto hivePartitioningOptions nell'oggetto ExternalDataConfiguration quando crei il file di definizione della tabella.
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
.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Esegui query su tabelle esterne
Per maggiori informazioni, consulta Eseguire query sui dati di Cloud Storage in tabelle esterne.
Esegui l'upgrade delle tabelle esterne a BigLake
Puoi eseguire l'upgrade delle tabelle basate su Cloud Storage a tabelle BigLake associando la tabella esterna a una connessione. Se vuoi utilizzare la memorizzazione nella cache dei metadati con la tabella BigLake, puoi specificare le relative impostazioni. Per ottenere i dettagli della tabella, come il formato di origine e l'URI di origine, consulta Ottenere informazioni sulla tabella.
Per aggiornare una tabella esterna a 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
Percorso risorsa Cloud Storage
Quando crei una tabella esterna basata su un'origine dati Cloud Storage, devi fornire il percorso dei dati.
Il percorso della risorsa Cloud Storage contiene il nome del bucket e l'oggetto (nome file). Ad esempio, se il bucket Cloud Storage è denominato
mybucket
e il file di dati è denominato myfile.csv
, il percorso della risorsa sarà
gs://mybucket/myfile.csv
.
BigQuery non supporta i percorsi delle risorse di Cloud Storage
che includono più barre consecutive dopo la doppia barra iniziale.
I nomi degli oggetti Cloud Storage possono contenere più caratteri barra ("/") consecutivi. Tuttavia, BigQuery converte più barre consecutive
in un'unica barra. Ad esempio, il seguente percorso della risorsa, sebbene valido in Cloud Storage, non funziona in BigQuery: gs://bucket/my//object//name
.
Per recuperare il percorso della risorsa Cloud Storage:
Apri la console di Cloud Storage.
Passa alla posizione dell'oggetto (file) che contiene i dati di origine.
Fai clic sul nome dell'oggetto.
Viene visualizzata la pagina Dettagli oggetto.
Copia il valore fornito nel campo URI gsutil, che inizia con
gs://
.
Supporto dei caratteri jolly per gli URI di Cloud Storage
Se i dati sono suddivisi in più file, puoi utilizzare un carattere jolly asterisco (*) per selezionare più file. L'utilizzo del carattere jolly * deve seguire queste regole:
- L'asterisco può apparire all'interno o alla fine del nome dell'oggetto.
- L'uso di più asterischi non è supportato. Ad esempio, il percorso
gs://mybucket/fed-*/temp/*.csv
non è valido. - L'utilizzo di un asterisco con il nome del bucket non è supportato.
Esempi:
L'esempio seguente mostra come selezionare tutti i file in tutte le cartelle che iniziano con il prefisso
gs://mybucket/fed-samples/fed-sample
:gs://mybucket/fed-samples/fed-sample*
L'esempio seguente mostra come selezionare solo i file con estensione
.csv
nella cartella denominatafed-samples
e nelle eventuali sottocartelle difed-samples
:gs://mybucket/fed-samples/*.csv
L'esempio seguente mostra come selezionare i file con un modello di denominazione
fed-sample*.csv
nella cartella denominatafed-samples
. Questo esempio non seleziona file nelle sottocartelle difed-samples
.gs://mybucket/fed-samples/fed-sample*.csv
Quando utilizzi lo strumento a riga di comando bq, su alcune piattaforme potrebbe essere necessario eseguire l'escape dell'asterisco.
Non puoi utilizzare un carattere jolly come un asterisco quando crei tabelle esterne collegate alle esportazioni di Datastore o Firestore.
Limitazioni
Per informazioni sulle limitazioni che si applicano alle tabelle esterne, consulta Limitazioni delle tabelle esterne.
Passaggi successivi
- Scopri di più sulle tabelle esterne.
- Scopri di più sulle tabelle BigLake.