Utilizzo del rilevamento automatico dello schema
Rilevamento automatico dello schema
Il rilevamento automatico degli schemi consente a BigQuery di dedurre lo schema per i dati CSV, JSON o Fogli Google. Il rilevamento automatico degli schemi è disponibile quando carichi dati in BigQuery e quando esegui query su un'origine dati esterna.
Quando il rilevamento automatico è abilitato, BigQuery deduce il tipo di dati per ogni colonna. BigQuery seleziona un file casuale nell'origine dati
ed esegue la scansione delle prime 500 righe di dati da utilizzare come campione rappresentativo.
BigQuery esamina quindi ogni campo e tenta di assegnare un tipo di dati a quel campo in base ai valori nel campione. Se tutte le righe di una colonna sono vuote, il rilevamento automatico verrà impostato in modo predefinito sul tipo di dati STRING
per la colonna.
Se non attivi il rilevamento automatico dello schema per i dati CSV, JSON o Fogli Google, devi fornire lo schema manualmente durante la creazione della tabella.
Non è necessario abilitare il rilevamento automatico dello schema per i file di esportazione Avro, Parquet, ORC, Firestore o di esportazione Datastore. Poiché questi formati file sono autodescritti, BigQuery deduce automaticamente lo schema della tabella dai dati di origine. Per i file Parquet, Avro e Orc, puoi facoltativamente fornire uno schema esplicito per eseguire l'override dello schema dedotto.
Puoi visualizzare lo schema rilevato per una tabella nei seguenti modi:
- Utilizzare la console Google Cloud.
- Utilizza il comando
bq show
dello strumento a riga di comando bq.
Quando BigQuery rileva schemi, in rare occasioni potrebbe modificare il nome di un campo per renderlo compatibile con la sintassi GoogleSQL.
Per informazioni sulle conversioni dei tipi di dati, consulta quanto segue:
- Conversione del tipo di dati durante il caricamento dei dati da Datastore
- Conversione del tipo di dati durante il caricamento dei dati da Firestore
- Conversioni Avro
- Conversioni Parquet
- Conversioni ORC
Caricamento dei dati tramite il rilevamento automatico dello schema
Per attivare il rilevamento automatico dello schema durante il caricamento dei dati, segui uno dei seguenti approcci:
- Nella sezione Schema della console Google Cloud, per Rilevamento automatico, seleziona l'opzione Parametri di schema e input.
- Nello strumento a riga di comando bq, utilizza il comando
bq load
con il parametro--autodetect
.
Quando il rilevamento automatico dello schema è abilitato, BigQuery tenta di dedurre automaticamente lo schema per i file CSV e JSON.
La logica di rilevamento automatico deduce i tipi di campi dello schema leggendo fino alle prime 500 righe di dati. Le righe iniziali vengono ignorate se è presente il flag --skip_leading_rows
. I tipi di campi si basano sulle righe che ne contengono il maggior numero.
Di conseguenza, il rilevamento automatico dovrebbe funzionare come previsto purché sia presente almeno una riga di dati con valori in ogni colonna/campo.
Il rilevamento automatico dello schema non viene utilizzato con i file Avro, i file Parquet, i file ORC, i file di esportazione Firestore o i file di esportazione Datastore. Quando carichi questi file in BigQuery, lo schema della tabella viene recuperato automaticamente dai dati di origine autodescritti.
Per utilizzare il rilevamento automatico degli schemi quando carichi dati JSON o CSV:
Console
Nella console Google Cloud, vai alla pagina BigQuery.
Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.
Espandi l'opzione
Azioni e fai clic su Apri.Nel riquadro dei dettagli, fai clic su Crea tabella
.Nella sezione Origine della pagina Crea tabella:
- In Crea tabella da, seleziona il tipo di origine che preferisci.
Nel campo di origine, cerca il bucket File/Cloud Storage o inserisci l'URI Cloud Storage. Tieni presente che non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella che stai creando.
In Formato file, seleziona CSV o JSON.
Nella sezione Destinazione della pagina Crea tabella:
In Nome set di dati, scegli il set di dati appropriato.
Nel campo Nome tabella, inserisci il nome della tabella che stai creando.
Verifica che l'opzione Tipo di tabella sia impostata su Tabella nativa.
Fai clic su Crea tabella.
bq
Esegui il comando bq load
con il parametro --autodetect
.
(Facoltativo) Fornisci il flag --location
e imposta il valore sulla tua
località.
Il seguente comando carica un file utilizzando il rilevamento automatico dello schema:
bq --location=LOCATION load \ --autodetect \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
Sostituisci quanto segue:
LOCATION
: il nome della tua località. Il flag--location
è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, imposta il valore del flag suasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.FORMAT
:NEWLINE_DELIMITED_JSON
oCSV
.DATASET
: il set di dati contenente la tabella in cui vengono caricati i dati.TABLE
: il nome della tabella in cui stai caricando i dati.PATH_TO_SOURCE
: è la posizione del file CSV o JSON.
Esempi:
Inserisci il seguente comando per caricare myfile.csv
dalla tua macchina locale in una tabella denominata mytable
archiviata in un set di dati denominato mydataset
.
bq load --autodetect --source_format=CSV mydataset.mytable ./myfile.csv
Inserisci il seguente comando per caricare myfile.json
dalla tua macchina locale in una tabella denominata mytable
archiviata in un set di dati denominato mydataset
.
bq load --autodetect --source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable ./myfile.json
API
Crea un job
load
che punta ai dati di origine. Per informazioni sulla creazione dei job, consulta Esecuzione di job BigQuery a livello di programmazione. Specifica la tua località nella proprietàlocation
all'interno della sezionejobReference
.Specifica il formato dei dati impostando la proprietà
sourceFormat
. Per utilizzare il rilevamento automatico dello schema, questo valore deve essere impostato suNEWLINE_DELIMITED_JSON
oCSV
.Utilizza la proprietà
autodetect
per impostare il rilevamento automatico dello schema sutrue
.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
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.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Per abilitare il rilevamento automatico dello schema, imposta la proprietà LoadJobConfig.autodetect su True
.
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.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Rilevamento automatico di schemi per origini dati esterne
Il rilevamento automatico degli schemi può essere utilizzato con origini dati esterne CSV, JSON e Fogli Google. Quando il rilevamento automatico dello schema è abilitato, BigQuery tenta di dedurre automaticamente lo schema dai dati di origine. Se non abiliti il rilevamento automatico dello schema per queste origini, devi fornire uno schema esplicito.
Non è necessario abilitare il rilevamento automatico dello schema quando esegui query su file di esportazione Avro, Parquet, ORC, Firestore o di esportazione Datastore. Questi formati file sono autodescritti, pertanto BigQuery deduce automaticamente lo schema della tabella dai dati di origine. Per i file Parquet, Avro e Orc, puoi scegliere di fornire uno schema esplicito per eseguire l'override dello schema dedotto.
Utilizzando la console Google Cloud, puoi attivare il rilevamento automatico degli schemi selezionando l'opzione Parametri di schema e input per Rilevamento automatico.
Con lo strumento a riga di comando bq, puoi attivare il rilevamento automatico dello schema quando crei un file di definizione della tabella per dati CSV, JSON o Fogli Google. Quando utilizzi lo strumento bq per creare un
file di definizione della tabella, passa il flag --autodetect
al comando mkdef
per
abilitare il rilevamento automatico dello schema oppure passa il flag --noautodetect
per disattivare
il rilevamento automatico.
Quando utilizzi il flag --autodetect
, l'impostazione autodetect
è impostata su true
nel file di definizione della tabella. Quando usi il flag --noautodetect
, l'impostazione autodetect
è impostata su false
. Se non fornisci una definizione dello schema per l'origine dati esterna quando crei una definizione di tabella e non utilizzi il flag --noautodetect
o --autodetect
, il valore predefinito dell'impostazione autodetect
è true
.
Quando crei un file di definizione di tabella utilizzando l'API, imposta il valore della proprietà autodetect
su true
o false
. Se imposti il criterio autodetect
su true
, il rilevamento automatico viene attivato. Se imposti il criterio autodetect
su false
, il rilevamento automatico viene disattivato.
Dettagli rilevamento automatico
Oltre a rilevare i dettagli dello schema, il rilevamento automatico riconosce quanto segue:
Compressione
BigQuery riconosce la compressione di file compatibile con gzip all'apertura di un file.
Valori di data e ora
BigQuery rileva i valori di data e ora in base alla formattazione dei dati di origine.
I valori nelle colonne DATE
devono essere nel seguente formato: YYYY-MM-DD
.
I valori nelle colonne TIME
devono essere nel seguente formato: HH:MM:SS[.SSSSSS]
(il componente dei secondi frazionari è facoltativo).
Per le colonne TIMESTAMP
, BigQuery rileva un'ampia gamma di
formati di timestamp, inclusi, a titolo esemplificativo:
YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM:SS.SSSSSS
YYYY/MM/DD HH:MM
Un timestamp può anche contenere un offset UTC o l'identificatore della zona UTC ("Z").
Ecco alcuni esempi di valori che BigQuery rileverà automaticamente come valori timestamp:
- 19-08-2018 12:11
- 19-08-2018 12:11:35.22
- 19/08/2018 12:11
- 19-08-2018 07:11:35.220 -05:00
Se BigQuery non riconosce il formato, carica la colonna come tipo di dati stringa. In questo caso, potresti dover pre-elaborare i dati di origine prima di caricarli. Ad esempio, se stai esportando dati CSV da un foglio di lavoro, imposta il formato della data in modo che corrisponda a uno degli esempi mostrati qui. In alternativa, puoi trasformare i dati dopo averli caricati in BigQuery.
Rilevamento automatico dello schema per i dati CSV
Delimitatore CSV
BigQuery rileva i seguenti delimitatori:
- virgola ( , )
- barra verticale ( | )
- scheda ( \t)
Intestazione CSV
BigQuery deduce le intestazioni confrontando la prima riga del file con altre righe del file. Se la prima riga contiene solo stringhe e le altre righe contengono altri tipi di dati, BigQuery presuppone che la prima riga sia una riga di intestazione. BigQuery assegna i nomi delle colonne in base ai nomi dei campi nella riga di intestazione. I nomi potrebbero essere modificati per rispettare le regole di denominazione per le colonne in BigQuery. Ad esempio, gli spazi verranno sostituiti con trattini bassi.
Altrimenti, BigQuery presuppone che la prima riga sia una riga di dati e assegna nomi di colonna generici come string_field_1
. Tieni presente che, dopo la creazione di una tabella, i nomi delle colonne non possono essere aggiornati nello schema, anche se puoi modificarli manualmente dopo la creazione della tabella. Un'altra opzione è fornire uno schema esplicito
anziché usare il rilevamento automatico.
Potresti avere un file CSV con una riga di intestazione, in cui tutti i campi di dati sono stringhe. In tal caso, BigQuery non rileverà automaticamente
che la prima riga è un'intestazione. Utilizza l'opzione --skip_leading_rows
per saltare la riga di intestazione. In caso contrario, l'intestazione verrà importata come dati. In questo caso, valuta anche di fornire uno schema esplicito, in modo da poter assegnare i nomi delle colonne.
Nuove righe CSV con virgolette
BigQuery rileva i caratteri di nuova riga tra virgolette in un campo CSV e non interpreta il carattere di nuova riga tra virgolette come limite di riga.
Rilevamento automatico di schemi per i dati JSON
Campi JSON nidificati e ripetuti
BigQuery deduce i campi nidificati e ripetuti nei file JSON. Se un
valore di campo è un oggetto JSON, BigQuery carica la colonna come
tipo RECORD
. Se il valore di un campo è un array, BigQuery carica la colonna come colonna ripetuta. Per un esempio di dati JSON con dati nidificati e ripetuti, consulta Caricamento di dati JSON nidificati e ripetuti.
Conversione di stringhe
Se attivi il rilevamento automatico degli schemi, BigQuery converte le stringhe in tipi booleani, numerici o data/ora, se possibile. Ad esempio,
utilizzando i seguenti dati JSON, il rilevamento automatico dello schema converte il campo id
in una colonna INTEGER
:
{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}
Per maggiori informazioni, consulta Caricare dati JSON da Cloud Storage.
Rilevamento automatico di schemi per Fogli Google
Per Fogli, BigQuery rileva automaticamente se la prima riga è una riga di intestazione, in modo simile al rilevamento automatico per i file CSV. Se la prima riga viene identificata come un'intestazione, BigQuery assegna i nomi delle colonne in base ai nomi dei campi nella riga di intestazione e ignora la riga. I nomi possono essere modificati per rispettare le regole di denominazione per le colonne in BigQuery. Ad esempio, gli spazi verranno sostituiti con trattini bassi.
Sicurezza della tabella
Per controllare l'accesso alle tabelle in BigQuery, consulta Introduzione ai controlli di accesso alle tabelle.