Creare un file di definizione della tabella per un'origine dati esterna
In questa pagina viene descritto come creare un file di definizione di tabella per un'origine dati esterna. Un'origine dati esterna è un'origine dati in cui puoi eseguire query direttamente anche se i dati non sono archiviati in BigQuery.
Un file di definizione della tabella contiene la definizione dello schema e i metadati di una tabella esterna, come il formato dei dati della tabella e le proprietà correlate. Quando crei un file di definizione della tabella, puoi utilizzare il rilevamento automatico dello schema per definire lo schema per un'origine dati esterna. Puoi fornire lo schema in linea oppure puoi fornire un file JSON contenente la definizione dello schema.
I file di definizione delle tabelle vengono utilizzati con lo strumento a riga di comando bq. Le proprietà in un file di definizione della tabella si applicano anche alla creazione di una ExternalDataConfiguration
quando utilizzi l'API REST. Non puoi usare i file di definizione delle tabelle quando crei
una tabella esterna con la console Google Cloud.
Puoi creare file di definizione della tabella per descrivere una tabella esterna permanente o temporanea per le seguenti origini dati esterne:
Cloud Storage
- Valori separati da virgola (CSV)
- JSON delimitato da nuova riga
- File Avro
- File di esportazione Datastore
- File ORC
- File Parquet
- File di esportazione Firestore
Google Drive
- Valori separati da virgola (CSV)
- JSON delimitato da nuova riga
- File Avro
- Fogli Google
Bigtable
Prima di iniziare
Per creare un file di definizione della tabella, ti occorre l'URI dell'origine dati:
- Per un'origine dati Drive, è necessario l'URI di Drive
- Per un'origine dati Cloud Storage, è necessario l'URI Cloud Storage
- Per un'origine dati Bigtable, è necessario l'URI Bigtable
Creare un file di definizione per i file CSV, JSON o Fogli Google
Utilizza uno dei seguenti metodi per creare un file di definizione della tabella per i file CSV, JSON o Fogli Google in Cloud Storage o Drive:
Usa il flag autodetect
Se specifichi un file CSV, JSON o Fogli Google senza includere una descrizione dello schema incorporata o un file di schema, puoi utilizzare il flag --autodetect
per impostare l'opzione "autodetect"
su true
nel file di definizione della tabella. Se il rilevamento automatico è abilitato, BigQuery fa il possibile per dedurre automaticamente lo schema. Per maggiori informazioni, consulta Rilevamento automatico dello schema per origini dati esterne.
Utilizza il rilevamento automatico con un'origine dati Cloud Storage
Crea un file di definizione della tabella per un'origine dati Cloud Storage:
Utilizza il comando
bq mkdef
con il flag--autodetect
per creare un file di definizione della tabella. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato del fileFILE_NAME
: il nome del file di definizione della tabellaURI
: URI Cloud StorageAd esempio,
gs://mybucket/myfile
.
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in nano. Il file dovrebbe essere simile al seguente per un'origine dati esterna in formato CSV. Nota che"autodetect"
è impostato sutrue
.{ "autodetect": true, "csvOptions": { "allowJaggedRows": false, "allowQuotedNewlines": false, "encoding": "UTF-8", "fieldDelimiter": ",", "quote": "\"", "skipLeadingRows": 0 }, "sourceFormat": "CSV", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni applicabili ai file CSV e Fogli Google. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.
Utilizzare il rilevamento automatico con un'origine dati Drive
Crea un file di definizione della tabella per un'origine dati Drive:
Utilizza il comando
bq mkdef
con il flag--autodetect
per creare una definizione di tabella. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato del fileFILE_NAME
: il nome del file di definizione della tabellaURI
: l'URI di DriveAd esempio,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd
.
Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in nano. Il file dovrebbe essere simile al seguente per un'origine dati esterna di Fogli Google. Avviso"autodetect"
è impostato sutrue
.{ "autodetect": true, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni applicabili ai file CSV e Fogli Google. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.Per specificare un foglio o un intervallo di celle specifico in un file di Fogli Google, aggiungi la proprietà
range
al file di definizione della tabella. Per eseguire query su un foglio specifico, specifica il nome del foglio. Per eseguire query su un intervallo di celle, specifica l'intervallo nel formato:sheet_name!top_left_cell_id:bottom_right_cell_id
, ad esempio,"Sheet1!A1:B20"
. Se il parametrorange
non viene specificato, viene utilizzato il primo foglio del file.
Utilizza uno schema in linea
Se non vuoi utilizzare il rilevamento automatico dello schema, puoi creare un file di definizione della tabella fornendo una definizione di schema in linea. Per fornire una definizione di schema incorporata, elenca i campi e i tipi di dati nella riga di comando nel seguente formato: FIELD:DATA_TYPE,FIELD:DATA_TYPE
.
Utilizza uno schema in linea con un'origine dati Cloud Storage o Drive
Crea una definizione di tabella per un'origine dati Cloud Storage o Drive utilizzando una definizione di schema incorporata:
Utilizza il comando
bq mkdef
con il flag--noautodetect
per creare una definizione di tabella. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ FIELD:DATA_TYPE,FIELD:DATA_TYPE > /tmp/FILE_NAME
Sostituisci quanto segue
SOURCE_FORMAT
: il formato del file di origineURI
: l'URI Cloud Storage o l'URI DriveAd esempio,
gs://mybucket/myfile
per Cloud Storage ohttps://drive.google.com/open?id=123ABCD123AbcD123Abcd
per Drive.FIELD:DATA_TYPE,FIELD:DATA_TYPE
: definizione dello schemaAd esempio,
Name:STRING,Address:STRING, ...
.FILE_NAME
: il nome del file di definizione della tabella
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in nano. Il file dovrebbe essere simile al seguente. Nota che"autodetect"
non è abilitato e le informazioni sullo schema vengono scritte nel file di definizione della tabella.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni applicabili ai file CSV e Fogli Google. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.
Utilizza un file di schema JSON
Se non vuoi utilizzare il rilevamento automatico o fornire una definizione di schema in linea, puoi creare un file di schema JSON e farvi riferimento durante la creazione del file di definizione della tabella. Crea manualmente il file di schema JSON sulla macchina locale. Non è supportato il riferimento a un file di schema JSON archiviato in Cloud Storage o in Drive.
Utilizza un file di schema con un'origine dati Cloud Storage
Crea una definizione di tabella per un'origine dati Cloud Storage utilizzando un file di schema JSON:
Utilizza il comando
bq mkdef
con il flag--noautodetect
per creare una definizione di tabella. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato del fileFILE_NAME
: il nome del file di definizione della tabellaURI
: URI Cloud StorageAd esempio,
gs://mybucket/myfile
.PATH_TO_SCHEMA_FILE
: la posizione del file di schema JSON sulla tua macchina locale
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in
nano. Il file dovrebbe essere simile al seguente. Nota che"autodetect"
non è abilitato e le informazioni sullo schema vengono scritte nel file di definizione della tabella.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni applicabili ai file CSV e Fogli Google. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.
Utilizzare un file di schema con un'origine dati Drive
Crea una definizione di tabella per un'origine dati Drive utilizzando un file di schema JSON:
Utilizza il comando
bq mkdef
con il flag--noautodetect
per creare una definizione di tabella. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --noautodetect \ --source_format=source_format \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
Sostituisci quanto segue:
SOURCE_FORMAT
: il formato del file di origineURI
: l'URI di DriveAd esempio,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd
.PATH_TO_SCHEMA_FILE
: la posizione del file di schema JSON sulla tua macchina localeFILE_NAME
: il nome del file di definizione della tabella
Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in nano. Il file dovrebbe essere simile al seguente. Nota che"autodetect"
non è abilitato e le informazioni dello schema vengono scritte nel file di definizione della tabella.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni applicabili ai file CSV e Fogli Google. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.Per specificare un foglio o un intervallo di celle specifico in un file di Fogli Google, aggiungi la proprietà
range
al file di definizione della tabella. Per eseguire query su un foglio specifico, specifica il nome del foglio. Per eseguire query su un intervallo di celle, specifica l'intervallo nel formato:sheet_name!top_left_cell_id:bottom_right_cell_id
, ad esempio,"Sheet1!A1:B20"
. Se il parametrorange
non viene specificato, viene utilizzato il primo foglio del file.
Creare un file di definizione per i formati autodescrittivi
Avro, Parquet e ORC sono formati autodescritti. I file di dati in questi formati contengono le proprie informazioni sullo schema. Se utilizzi uno di questi formati come origine dati esterna, BigQuery recupera automaticamente lo schema utilizzando i dati di origine. Quando crei una definizione di tabella, non è necessario utilizzare il rilevamento automatico dello schema, né fornire una definizione di schema o un file di schema in linea.
Puoi creare un file di definizione della tabella per i dati Avro, Parquet o ORC archiviati in Cloud Storage o Drive:
Usa il comando
bq mkdef
per creare una definizione della tabella.bq mkdef \ --source_format=FORMAT \ "URI" > FILE_NAME
Sostituisci quanto segue:
FORMAT
: il formato di origineURI
: l'URI Cloud Storage o l'URI DriveAd esempio,
gs://mybucket/myfile
per Cloud Storage ohttps://drive.google.com/open?id=123ABCD123AbcD123Abcd
per Drive.FILE_NAME
: il nome del file di definizione della tabella
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Il file è simile al seguente:
{ "sourceFormat": "AVRO", "sourceUris": [ "URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come
maxBadRecords
eignoreUnknownValues
. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.
Crea un file di definizione per i dati partizionati in hive
Usa il comando bq mkdef
con i flag hive_partitioning_mode
e
hive_partitioning_source_uri_prefix
per
creare un file di definizione per i dati partizionati hive archiviati in
Cloud Storage, Amazon Simple Storage Service (Amazon S3) o Azure Blob Storage.
Crea un file di definizione per Datastore e Firestore
Se utilizzi un'esportazione di Datastore o Firestore come origine dati esterna, BigQuery recupera automaticamente lo schema utilizzando i dati di origine autodescrittivi. Quando crei una definizione di tabella, non è necessario fornire una definizione di schema o un file di schema in linea.
Puoi creare un file di definizione della tabella per l'esportazione di dati di Datastore e Firestore archiviati in Cloud Storage:
Usa il comando
bq mkdef
per creare una definizione della tabella. Non è necessario utilizzare il flag--noautodetect
con i file di backup di Datastore o Firestore. Il rilevamento automatico dello schema è disabilitato per questi tipi di file. Il comandomkdef
genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file:/tmp/file_name
.bq mkdef \ --source_format=DATASTORE_BACKUP \ "URI" > /tmp/FILE_NAME
Sostituisci quanto segue:
URI
: URI Cloud StorageFILE_NAME
: il nome del file di definizione della tabella
Il formato di origine
DATASTORE_BACKUP
viene utilizzato sia per Datastore che per Firestore.(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando
nano /tmp/file_name
apre il file in nano. Il file dovrebbe essere simile al seguente. Tieni presente che non è necessario l'impostazione"autodetect"
.{ "sourceFormat": "DATASTORE_BACKUP", "sourceUris": [ "gs://URI" ] }
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare impostazioni quali
maxBadRecords
eignoreUnknownValues
. Non sono presenti impostazioni di configurazione specifiche per i file di esportazione di Datastore e Firestore. Per maggiori informazioni, consultaExternalDataConfiguration
nel riferimento delle API.
Crea un file di definizione per Bigtable
Quando crei un file di definizione della tabella per Bigtable, generi manualmente il file in formato JSON. L'utilizzo del comando mkdef
per creare una definizione di tabella non è attualmente supportato per le origini dati Bigtable.
Per Bigtable non è supportato nemmeno il rilevamento automatico dello schema. Per un elenco delle opzioni di definizione delle tabelle Bigtable, vedi BigtableOptions
nel riferimento dell'API REST.
Un file di definizione della tabella JSON per Bigtable è simile al seguente. Utilizzando questo file di definizione della tabella, BigQuery legge i dati da una singola famiglia di colonne, interpretando i valori come numeri interi con codifica binaria.
{ "sourceFormat": "BIGTABLE", "sourceUris": [ "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_NAME" ], "bigtableOptions": { "columnFamilies" : [ { "familyId": "FAMILY_ID", "type": "INTEGER", "encoding": "BINARY" } ] } }
Sostituisci quanto segue:
PROJECT_ID
: il progetto contenente il cluster BigtableINSTANCE_ID
: l'ID dell'istanza BigtableTABLE_NAME
: il nome della tabella su cui stai eseguendo la queryFAMILY_ID
: l'identificatore della famiglia di colonne
Per ulteriori informazioni, consulta Recupero dell'URI Bigtable.
Supporto dei caratteri jolly per i file di definizione delle tabelle
Se i dati sono separati in più file, puoi utilizzare un carattere jolly asterisco (*) per selezionare più file. L'utilizzo del carattere jolly asterisco deve seguire queste regole:
- L'asterisco può essere visualizzato all'interno del nome dell'oggetto o alla fine del nome.
- 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 file con un pattern di denominazione di
fed-sample*.csv
nella cartella denominatafed-samples
. In questo esempio non vengono selezionati i 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'interpretazione letterale dell'asterisco.
Se utilizzi un carattere jolly asterisco, racchiudi il bucket e il nome file tra virgolette. Ad esempio, se hai due file denominati fed-sample000001.csv
e fed-sample000002.csv
e vuoi utilizzare un asterisco per selezionarli entrambi, l'URI del bucket sarà "gs://mybucket/fed-sample*"
.
Il carattere jolly *
non è consentito durante la creazione di file di definizione delle tabelle per le seguenti origini dati:
- Bigtable. Per i dati Bigtable è possibile specificare una sola origine dati. Il valore dell'URI deve essere un URL HTTPS valido per una tabella Bigtable.
- Datastore o Firestore. Le esportazioni di Datastore
o Firestore archiviate in
Cloud Storage. Per i backup di Datastore, è possibile specificare una sola origine dati. Il valore dell'URI deve terminare con
.backup_info
o.export_metadata
. - Drive. Dati archiviati su Drive.
Passaggi successivi
- Scopri come eseguire query sui dati di Cloud Storage.
- Scopri come eseguire query sui dati di Drive.
- Scopri come eseguire query sui dati Bigtable.