Caricamento dei dati Parquet da Cloud Storage
Questa pagina fornisce una panoramica del caricamento dei dati Parquet da Cloud Storage in BigQuery.
Parquet è un formato di dati open source orientato alle colonne ampiamente utilizzato nell'ecosistema Apache Hadoop.
Quando carichi dati Parquet da Cloud Storage, puoi caricarli in una nuova tabella o partizione oppure puoi aggiungere o sovrascrivere una tabella o partizione esistente. Quando i dati vengono caricati in BigQuery, vengono convertiti in formato a colonne per Condensatore (il formato di archiviazione di BigQuery).
Quando carichi dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa località a livello di una o più regioni del bucket Cloud Storage.
Per informazioni sul caricamento dei dati Parquet da un file locale, consulta Caricamento di dati da file locali.
Limitazioni
Quando carichi dati in BigQuery da un bucket Cloud Storage, devi rispettare le seguenti limitazioni:
- Se la località del set di dati è impostata su un valore diverso da
US
, il bucket Cloud Storage deve trovarsi nella stessa regione o all'interno della stessa multiregione del set di dati. - BigQuery non garantisce la coerenza dei dati per le origini dati esterne. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono causare comportamenti imprevisti.
BigQuery non supporta il controllo delle versioni degli oggetti di Cloud Storage. Se includi un numero di generazione nell'URI Cloud Storage, il job di caricamento non va a buon fine.
Per impostazione predefinita, il caricamento dei dati Parquet non supporta nomi di colonna flessibili. Per registrarti a questa anteprima, compila il modulo di registrazione.
Non puoi utilizzare un carattere jolly nell'URI Cloud Storage se uno o più file da caricare hanno schemi diversi. Qualsiasi differenza nella posizione delle colonne viene considerata uno schema diverso.
Requisiti del file di input
Per evitare errori resourcesExceeded
durante il caricamento di file Parquet in BigQuery, segui queste linee guida:
- Mantieni le dimensioni delle righe fino a un massimo di 50 MB.
- Se i dati di input contengono più di 100 colonne, ti consigliamo di ridurre le dimensioni della pagina in modo che siano inferiori a quelle predefinite (1 * 1024 * 1024 byte). Ciò è particolarmente utile se utilizzi una compressione significativa.
Prima di iniziare
Concedi i ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività nel documento e crea un set di dati per archiviare i tuoi dati.
Autorizzazioni obbligatorie
Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati in tabelle e partizioni BigQuery. Se stai caricando i dati da Cloud Storage, devi avere anche le autorizzazioni IAM per accedere al bucket che contiene i tuoi dati.
Autorizzazioni per caricare i dati in BigQuery
Per caricare i dati in una nuova tabella o partizione BigQuery oppure per aggiungere o sovrascrivere una tabella o una partizione esistente, devi disporre delle seguenti autorizzazioni IAM:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per caricare i dati in una tabella o partizione BigQuery:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(include l'autorizzazionebigquery.jobs.create
)bigquery.user
(include l'autorizzazionebigquery.jobs.create
)bigquery.jobUser
(include l'autorizzazionebigquery.jobs.create
)
Inoltre, se disponi dell'autorizzazione bigquery.datasets.create
, puoi creare e aggiornare le tabelle utilizzando un job di caricamento nei set di dati che crei.
Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, consulta Autorizzazioni e ruoli predefiniti.
Autorizzazioni per caricare i dati da Cloud Storage
Per ottenere le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage,
chiedi all'amministratore di concederti il ruolo IAM
Amministratore Storage (roles/storage.admin
) per il bucket.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:
Autorizzazioni obbligatorie
Per caricare i dati da un bucket Cloud Storage sono necessarie le seguenti autorizzazioni:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
Potresti anche essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.
crea un set di dati
Crea un set di dati BigQuery per archiviare i tuoi dati.
Schemi Parquet
Quando carichi i file Parquet in BigQuery, lo schema della tabella viene recuperato automaticamente dai dati di origine autodescritti. Quando BigQuery recupera lo schema dai dati di origine, viene utilizzato l'ultimo file, in ordine alfabetico.
Ad esempio, hai i seguenti file Parquet in Cloud Storage:
gs://mybucket/00/ a.parquet z.parquet gs://mybucket/01/ b.parquet
L'esecuzione di questo comando nello strumento a riga di comando bq consente di caricare tutti i file (come elenco separato da virgole) e lo schema deriva da mybucket/01/b.parquet
:
bq load \ --source_format=PARQUET \ dataset.table \ "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
Quando carichi più file Parquet con schemi diversi, le colonne identiche specificate in più schemi devono avere la stessa modalità in ogni definizione di schema.
Quando BigQuery rileva lo schema, alcuni tipi di dati Parquet vengono convertiti in tipi di dati BigQuery per renderli compatibili con la sintassi di GoogleSQL. Per ulteriori informazioni, consulta Conversioni Parquet.
Per fornire uno schema per la creazione di tabelle esterne, imposta la proprietàreferenceFileSchemaUri
nell'API BigQuery o il parametro --reference_file_schema_uri
nello strumento a riga di comando bq
sull'URL del file di riferimento.
Ad esempio, --reference_file_schema_uri="gs://mybucket/schema.parquet"
.
Compressione parchè
BigQuery supporta i seguenti codec di compressione per i contenuti dei file Parquet:
GZip
LZO_1C
LZO_1X
LZ4_RAW
Snappy
ZSTD
Caricamento dei dati Parquet in una nuova tabella
Puoi caricare i dati Parquet in una nuova tabella utilizzando uno dei seguenti:
- Nella console Google Cloud
- Il comando
bq load
dello strumento a riga di comando bq - Metodo API
jobs.insert
e configurazione di un jobload
- Le librerie client
Per caricare i dati Parquet da Cloud Storage in una nuova tabella BigQuery:
Console
Nella console Google Cloud, vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto, quindi seleziona un set di dati.
- Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
- Nel riquadro Crea tabella, specifica i seguenti dettagli:
- Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da.
Poi esegui le seguenti operazioni:
- Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage. 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 da creare, aggiungere o sovrascrivere.
- In Formato file, seleziona Parquet.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- Nel campo Tabella, inserisci il nome della tabella che vuoi creare.
- Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
- Nella sezione Schema non è necessaria alcuna azione. Lo schema si descrive autonomamente nei file Parquet.
- (Facoltativo) Specifica le impostazioni di partizione e cluster. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo delle tabelle in cluster.
- Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
- In Preferenza di scrittura, lascia selezionata l'opzione Scrivi se vuoto. Questa opzione consente di creare una nuova tabella in cui caricare i dati.
- Se in una riga vuoi ignorare i valori che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
- In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.
- Fai clic su Crea tabella.
SQL
Utilizza l'istruzione DDL LOAD DATA
.
Nell'esempio seguente viene caricato un file Parquet nella nuova tabella mytable
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor query, inserisci la seguente istruzione:
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
bq
Utilizza il comando bq load
, specifica PARQUET
con il flag --source_format
e includi un URI Cloud Storage.
Puoi includere un singolo URI, un elenco di URI separati da virgole o un URI contenente un caratteri jolly.
(Facoltativo) Fornisci il flag --location
e imposta il valore sulla tua
località.
Altri flag facoltativi includono:
--time_partitioning_type
: abilita il partizionamento basato sul tempo su una tabella e imposta il tipo di partizione. I valori possibili sonoHOUR
,DAY
,MONTH
eYEAR
. Questo flag è facoltativo quando crei una tabella partizionata in una colonnaDATE
,DATETIME
oTIMESTAMP
. Il tipo di partizione predefinito per il partizionamento basato sul tempo èDAY
. Non puoi modificare la specifica di partizionamento in una tabella esistente.--time_partitioning_expiration
: un numero intero che specifica (in secondi) quando deve essere eliminata una partizione basata sul tempo. La data di scadenza restituisce la data UTC della partizione più il valore intero.--time_partitioning_field
: la colonnaDATE
oTIMESTAMP
utilizzata per creare una tabella partizionata. Se il partizionamento basato sul tempo è abilitato senza questo valore, viene creata una tabella partizionata per data di importazione.--require_partition_filter
: se abilitata, questa opzione richiede agli utenti di includere una clausolaWHERE
che specifichi le partizioni su cui eseguire la query. La richiesta di un filtro di partizionamento può ridurre i costi e migliorare le prestazioni. Per ulteriori informazioni, consulta Esecuzione di query sulle tabelle partizionate.--clustering_fields
: un elenco separato da virgole di massimo quattro nomi di colonna utilizzato per creare una tabella in cluster.--destination_kms_key
: la chiave Cloud KMS per la crittografia dei dati della tabella.Per ulteriori informazioni sulle tabelle partizionate, consulta:
Per ulteriori informazioni sulle tabelle in cluster, consulta:
Per saperne di più sulla crittografia delle tabelle, vedi:
Per caricare i dati Parquet in BigQuery, inserisci il seguente comando:
bq --location=LOCATION load \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
Sostituisci quanto segue:
LOCATION
: la tua posizione. Il flag--location
è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag suasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.FORMAT
:PARQUET
.DATASET
: un set di dati esistente.TABLE
: il nome della tabella in cui stai caricando i dati.PATH_TO_SOURCE
: un URI Cloud Storage completo o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.
Esempi:
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
in una
tabella denominata mytable
in mydataset
.
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
in una nuova tabella partizionata per data di importazione denominata mytable
in mydataset
.
bq load \
--source_format=PARQUET \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.parquet
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
in una
tabella partizionata denominata mytable
in mydataset
. La tabella è partizionata
nella colonna mytimestamp
.
bq load \
--source_format=PARQUET \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.parquet
Il seguente comando carica i dati da più file in gs://mybucket/
in una tabella denominata mytable
in mydataset
. L'URI Cloud Storage utilizza
un carattere jolly.
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata*.parquet
Il seguente comando carica i dati da più file in gs://mybucket/
in una tabella denominata mytable
in mydataset
. Il comando include un elenco separato da virgole di URI Cloud Storage con caratteri jolly.
bq load \
--source_format=PARQUET \
mydataset.mytable \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
API
Crea un job
load
che punta ai dati di origine in Cloud Storage.(Facoltativo) Specifica la tua località nella proprietà
location
nella sezionejobReference
della risorsa job.La proprietà
source URIs
deve essere completa nel formatogs://BUCKET/OBJECT
. Ogni URI può contenere un carattere jolly "*"Specifica il formato dei dati Parquet impostando la proprietà
sourceFormat
suPARQUET
.Per controllare lo stato del job, chiama
jobs.get(JOB_ID*)
, sostituendo JOB_ID con l'ID del job restituito dalla richiesta iniziale.- Se
status.state = DONE
, il job è stato completato correttamente. - Se è presente la proprietà
status.errorResult
, la richiesta non è andata a buon fine e l'oggetto include informazioni che descrivono l'errore. Quando una richiesta non va a buon fine, non viene creata alcuna tabella e non vengono caricati dati. - Se
status.errorResult
non è presente, il job è stato completato correttamente; anche se potrebbero essersi verificati alcuni errori non irreversibili, come problemi di importazione di alcune righe. Gli errori non irreversibili sono elencati nella proprietàstatus.errors
dell'oggetto job restituito.
- Se
Note dell'API:
I job di caricamento sono atomici e coerenti: se un job di caricamento ha esito negativo, nessuno dei dati è disponibile e, se un job di caricamento ha esito positivo, sono disponibili tutti i dati.
Come best practice, genera un ID univoco e passalo come
jobReference.jobId
quando chiamijobs.insert
per creare un job di caricamento. Questo approccio è più solido in caso di errore di rete perché il client può eseguire il polling o riprovare sull'ID job noto.La chiamata a
jobs.insert
per un determinato ID job è idempotente. Puoi riprovare tutte le volte che vuoi sullo stesso ID job e al massimo una di queste operazioni avrà esito positivo.
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
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.
Usa il metodo Client.load_table_from_uri() per avviare un job di caricamento da Cloud Storage. Per utilizzare Parquet, imposta la proprietà LoadJobConfig.source_format sulla stringaPARQUET
e passa la configurazione del job come argomento job_config
al metodo load_table_from_uri()
.
Aggiunta o sovrascrittura di una tabella con dati Parquet
Puoi caricare dati aggiuntivi in una tabella dai file di origine o aggiungendo i risultati della query.
Nella console Google Cloud, utilizza l'opzione Preferenza di scrittura per specificare l'azione da eseguire quando carichi i dati da un file di origine o da un risultato di query.
Quando carichi dati aggiuntivi in una tabella, hai a disposizione le seguenti opzioni:
Opzione della console | flag dello strumento bq | Proprietà API BigQuery | Descrizione |
---|---|---|---|
Scrivi se vuota | Funzionalità non supportata | WRITE_EMPTY |
Scrive i dati solo se la tabella è vuota. |
Aggiungi a tabella | --noreplace o --replace=false ; se --[no]replace non è specificato, il valore predefinito è Aggiungi |
WRITE_APPEND |
(Predefinito) Accoda i dati alla fine della tabella. |
Sovrascrivi tabella | --replace o --replace=true |
WRITE_TRUNCATE |
Cancella tutti i dati esistenti in una tabella prima di scrivere nuovi dati. Questa azione elimina anche lo schema della tabella, la sicurezza a livello di riga e rimuove qualsiasi chiave Cloud KMS. |
Se carichi i dati in una tabella esistente, il job di caricamento può aggiungere i dati o sovrascrivere la tabella.
Puoi aggiungere o sovrascrivere una tabella utilizzando uno dei seguenti metodi:
- Nella console Google Cloud
- Il comando
bq load
dello strumento a riga di comando bq - Metodo API
jobs.insert
e configurazione di un jobload
- Le librerie client
Per aggiungere o sovrascrivere una tabella con dati Parquet:
Console
Nella console Google Cloud, vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto, quindi seleziona un set di dati.
- Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
- Nel riquadro Crea tabella, specifica i seguenti dettagli:
- Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da.
Poi esegui le seguenti operazioni:
- Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage. 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 da creare, aggiungere o sovrascrivere.
- In Formato file, seleziona Parquet.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- Nel campo Tabella, inserisci il nome della tabella che vuoi creare.
- Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
- Nella sezione Schema non è necessaria alcuna azione. Lo schema si descrive autonomamente nei file Parquet.
- (Facoltativo) Specifica le impostazioni di partizione e cluster. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo delle tabelle in cluster. Non puoi convertire una tabella in una tabella partizionata o in cluster aggiungendola o sovrascrivendola. La console Google Cloud non supporta l'aggiunta o la sovrascrittura di tabelle partizionate o in cluster in un job di caricamento.
- Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
- In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi tabella.
- Se in una riga vuoi ignorare i valori che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
- In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.
- Fai clic su Crea tabella.
SQL
Utilizza l'istruzione DDL LOAD DATA
.
Nell'esempio seguente viene aggiunto un file Parquet alla tabella mytable
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'Editor query, inserisci la seguente istruzione:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
bq
Inserisci il comando bq load
con il flag --replace
per sovrascrivere la tabella. Utilizza il flag --noreplace
per aggiungere dati alla tabella. Se non viene specificato alcun flag, l'impostazione predefinita prevede l'aggiunta di dati. Fornisci il flag --source_format
e impostalo su PARQUET
. Poiché gli schemi Parquet vengono recuperati automaticamente dai dati di origine autodescritti, non è necessario fornire una definizione dello schema.
(Facoltativo) Fornisci il flag --location
e imposta il valore sulla tua
località.
Altri flag facoltativi includono:
--destination_kms_key
: la chiave Cloud KMS per la crittografia dei dati della tabella.
bq --location=LOCATION load \ --[no]replace \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
Sostituisci quanto segue:
location
: la tua posizione. Il flag--location
è facoltativo. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.format
:PARQUET
.dataset
: un set di dati esistente.table
: il nome della tabella in cui stai caricando i dati.path_to_source
: un URI Cloud Storage completo o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.
Esempi:
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
e
sovrascrive una tabella denominata mytable
in mydataset
.
bq load \
--replace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
e
aggiunge i dati a una tabella denominata mytable
in mydataset
.
bq load \
--noreplace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
Per informazioni su come aggiungere e sovrascrivere le tabelle partizionate utilizzando lo strumento a riga di comando bq, consulta Aggiunta e sovrascrittura di tabella partizionata partizionate.
API
Crea un job
load
che punta ai dati di origine in Cloud Storage.(Facoltativo) Specifica la tua località nella proprietà
location
nella sezionejobReference
della risorsa job.La proprietà
source URIs
deve essere completa, nel formatogs://BUCKET/OBJECT
. Puoi includere più URI sotto forma di elenco separato da virgole. Tieni presente che sono supportati anche i caratteri jolly.Specifica il formato dei dati impostando la proprietà
configuration.load.sourceFormat
suPARQUET
.Specifica la preferenza di scrittura impostando la proprietà
configuration.load.writeDisposition
suWRITE_TRUNCATE
oWRITE_APPEND
.
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
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.
Per sostituire le righe in una tabella esistente, imposta la proprietà LoadJobConfig.write_disposition su WRITE_TRUNCATE.Caricamento dei dati Parquet partizionati hive
BigQuery supporta il caricamento dei dati Parquet partizionati hive archiviati in Cloud Storage e compila le colonne di partizionamento hive come colonne nella tabella gestita BigQuery di destinazione. Per maggiori informazioni, consulta Caricamento di dati partizionati esternamente.
Conversioni Parquet
Questa sezione descrive in che modo BigQuery analizza i vari tipi di dati durante il caricamento dei dati Parquet.
Alcuni tipi di dati Parquet (ad esempio INT32
, INT64
, BYTE_ARRAY
e FIXED_LEN_BYTE_ARRAY
) possono essere convertiti in più tipi di dati BigQuery. Per assicurarti che BigQuery converta correttamente i tipi di dati Parquet, specifica il tipo di dati appropriato nel file Parquet.
Ad esempio, per convertire il tipo di dati Parquet INT32
nel tipo di dati BigQuery DATE
, specifica quanto segue:
optional int32 date_col (DATE);
BigQuery converte i tipi di dati Parquet nei tipi di dati BigQuery descritti nelle sezioni seguenti.
Conversioni dei tipi
Tipo di dati BigQuery | ||
---|---|---|
BOOLEAN |
Nessun valore | BOOLEANO |
INT32 | Nessuno, INTEGER (UINT_8 , UINT_16 ,
UINT_32 , INT_8 , INT_16 ,
INT_32 )
|
INT64 |
INT32 | DECIMALE | NUMERIC, BIGNUMERIC o STRING |
INT32 |
DATE |
DATA |
INT64 |
Nessuno, INTEGER (UINT_64 , INT_64 )
|
INT64 |
INT64 | DECIMALE | NUMERIC, BIGNUMERIC o STRING |
INT64 |
TIMESTAMP , precision=MILLIS
(TIMESTAMP_MILLIS )
|
TIMESTAMP |
INT64 |
TIMESTAMP , precision=MICROS
(TIMESTAMP_MICROS )
|
TIMESTAMP |
INT96 |
Nessun valore | TIMESTAMP |
FLOAT |
Nessun valore | FLOAT64 |
DOUBLE |
Nessun valore | FLOAT64 |
BYTE_ARRAY |
Nessun valore | BYTES |
BYTE_ARRAY |
STRING (UTF8 ) |
STRING |
FIXED_LEN_BYTE_ARRAY | DECIMALE | NUMERIC, BIGNUMERIC o STRING |
FIXED_LEN_BYTE_ARRAY |
Nessun valore | BYTES |
I gruppi nidificati vengono convertiti in tipi STRUCT
.
Non sono supportate altre combinazioni di tipi Parquet e tipi convertiti.
Tipi logici non firmati
I tipi di Parquet UINT_8
, UINT_16
, UINT_32
e UINT_64
non sono firmati.
BigQuery tratterà i valori con questi tipi come non firmati durante il caricamento in una colonna INTEGER
firmata di BigQuery. Nel caso di UINT_64
, verrà restituito un errore
se il valore senza segno supera il valore massimo INTEGER
di
9.223.372.036.854.775.807.
Tipo logico decimale
I tipi logici Decimal
possono essere convertiti in tipi NUMERIC
, BIGNUMERIC
o STRING
. Il tipo convertito dipende dai parametri di precisione e scala del tipo logico decimal
e dai tipi di target decimali specificati. Specifica il tipo di target decimale come segue:
- Per un job di caricamento con l'API
jobs.insert
: utilizza il campoJobConfigurationLoad.decimalTargetTypes
. - Per un job di caricamento con il comando
bq load
nello strumento a riga di comando bq, utilizza il flag--decimal_target_types
. - Per una query su una tabella con origini esterne: utilizza il campo
ExternalDataConfiguration.decimalTargetTypes
. - Per una tabella esterna permanente creata con un DDL:
utilizza l'opzione
decimal_target_types
.
Tipo logico enum
Enum
tipi logici possono essere convertiti in STRING
o BYTES
. Specifica il tipo di target convertito come segue:
- Per un job di caricamento con l'API
jobs.insert
: utilizza il campoJobConfigurationLoad.parquetOptions
. - Per un job di caricamento con il comando
bq load
nello strumento a riga di comando bq, utilizza il flag--parquet_enum_as_string
. - Per una tabella esterna permanente creata con
bq mk
: utilizza il flag--parquet_enum_as_string
.
Elenca tipo logico
Puoi attivare l'inferenza dello schema per i tipi logici Parquet LIST
. BigQuery verifica se il nodo LIST
è in forma standard o in una delle forme descritte dalle regole di compatibilità con le versioni precedenti:
// standard form
<optional | required> group <name> (LIST) {
repeated group list {
<optional | required> <element-type> element;
}
}
In caso affermativo, il campo corrispondente per il nodo LIST
nello schema convertito viene considerato come se il nodo presentasse il seguente schema:
repeated <element-type> <name>
I nodi "elenco" ed "elemento" sono omessi.
- Per un job di caricamento con l'API
jobs.insert
: utilizza il campoJobConfigurationLoad.parquetOptions
. - Per un job di caricamento con il comando
bq load
nello strumento a riga di comando bq, utilizza il flag--parquet_enable_list_inference
. - Per una tabella esterna permanente creata con
bq mk
: utilizza il flag--parquet_enable_list_inference
.
Dati geospaziali
Puoi caricare file parquet che contengono WKT, WKB con codifica esadecimale o GeoJSON in una
colonna STRING
oppure WKB in una colonna BYTE_ARRAY
specificando uno
schema BigQuery con il tipo GEOGRAPHY
. Vedi Caricamento dei dati
geospaziali.
Conversioni nome colonna
Il nome di una colonna può contenere lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_) e deve iniziare con una lettera o un trattino basso. Se utilizzi nomi di colonna flessibili, BigQuery supporta l'inizio del nome di una colonna con un numero. Presta attenzione quando avvii colonne con un numero, poiché l'utilizzo di nomi di colonna flessibili con l'API BigQuery Storage Read o l'API BigQuery Storage Write richiede una gestione speciale. Per ulteriori informazioni sul supporto dei nomi delle colonne flessibili, consulta i nomi delle colonne flessibili.
I nomi delle colonne possono avere una lunghezza massima di 300 caratteri. I nomi di colonna non possono utilizzare nessuno dei seguenti prefissi:
_TABLE_
_FILE_
_PARTITION
_ROW_TIMESTAMP
__ROOT__
_COLIDENTIFIER
Non sono consentiti nomi di colonna duplicati anche se le maiuscole e le minuscole sono diverse. Ad esempio, una
colonna denominata Column1
è considerata identica a una colonna denominata column1
. Per ulteriori informazioni sulle regole di denominazione delle colonne, consulta Nomi delle colonne nel riferimento di GoogleSQL.
Se il nome di una tabella (ad esempio test
) è uguale a uno dei nomi di colonna
(ad esempio test
), l'espressione SELECT
interpreta la colonna test
come
una STRUCT
contenente tutte le altre colonne della tabella. Per evitare questo conflitto, usa
uno dei seguenti metodi:
Evita di utilizzare lo stesso nome per una tabella e le relative colonne.
Assegna alla tabella un alias diverso. Ad esempio, la seguente query assegna un alias di tabella
t
alla tabellaproject1.dataset.test
:SELECT test FROM project1.dataset.test AS t;
Includi il nome della tabella quando fai riferimento a una colonna. Ad esempio:
SELECT test.test FROM project1.dataset.test;
Nomi delle colonne flessibili
Hai maggiore flessibilità nella scelta dei nomi per le colonne, tra cui l'accesso esteso ai caratteri in lingue diverse dall'inglese e a simboli aggiuntivi.
I nomi di colonna flessibili supportano i seguenti caratteri:
- Qualsiasi lettera in qualsiasi lingua, come rappresentata dall'espressione regolare Unicode
\p{L}
. - Qualsiasi carattere numerico in qualsiasi lingua, come rappresentato dall'espressione regolare Unicode
\p{N}
. - Qualsiasi carattere di punteggiatura del connettore, inclusi i trattini bassi, come rappresentato dall'espressione regolare Unicode
\p{Pc}
. - Un trattino o un trattino come rappresentati dall'espressione regolare Unicode
\p{Pd}
. - Qualsiasi contrassegno destinato ad accompagnare un altro carattere come rappresentato dall'espressione regolare Unicode
\p{M}
. Ad esempio accenti, dieresi o riquadri di accompagnamento. - I seguenti caratteri speciali:
- La e commerciale (
&
) rappresentata dall'espressione regolare Unicode\u0026
. - Un segno di percentuale (
%
) come rappresentato dall'espressione regolare Unicode\u0025
. - Un segno di uguale (
=
) come rappresentato dall'espressione regolare Unicode\u003D
. - Un segno più (
+
) come rappresentato dall'espressione regolare Unicode\u002B
. - Due punti (
:
) come rappresentati dall'espressione regolare Unicode\u003A
. - Un apostrofo (
'
) come rappresentato dall'espressione regolare Unicode\u0027
. - Un segno di minore (
<
) come rappresentato dall'espressione regolare Unicode\u003C
. - Un segno di maggiore di (
>
) come rappresentato dall'espressione regolare Unicode\u003E
. - Un segno numerico (
#
) come rappresentato dall'espressione regolare Unicode\u0023
. - Una linea verticale (
|
) come rappresentata dall'espressione regolare Unicode\u007c
. - Spazio vuoto.
- La e commerciale (
I nomi di colonna flessibili non supportano i seguenti caratteri speciali:
- Un punto esclamativo (
!
) come rappresentato dall'espressione regolare Unicode\u0021
. - Una virgoletta (
"
) rappresentata dall'espressione regolare Unicode\u0022
. - Un simbolo del dollaro (
$
) come rappresentato dall'espressione regolare Unicode\u0024
. - Una parentesi aperta (
(
) come rappresentata dall'espressione regolare Unicode\u0028
. - Una parentesi chiusa (
)
) come rappresentata dall'espressione regolare Unicode\u0029
. - Un asterisco (
*
) come rappresentato dall'espressione regolare Unicode\u002A
. - Una virgola (
,
) come rappresentata dall'espressione regolare Unicode\u002C
. - Un punto (
.
) come rappresentato dall'espressione regolare Unicode\u002E
. - Una barra (
/
) come rappresentata dall'espressione regolare Unicode\u002F
. - Un punto e virgola (
;
) come rappresentato dall'espressione regolare Unicode\u003B
. - Un punto interrogativo (
?
) come rappresentato dall'espressione regolare Unicode\u003F
. - Un simbolo di chiocciola (
@
) come rappresentato dall'espressione regolare Unicode\u0040
. - Una parentesi quadra aperta (
[
) come rappresentata dall'espressione regolare Unicode\u005B
. - Una barra rovesciata (
\
) come rappresentata dall'espressione regolare Unicode\u005C
. - Una parentesi quadra chiusa (
]
) come rappresentata dall'espressione regolare Unicode\u005D
. - Un accento circonflesso (
^
) come rappresentato dall'espressione regolare Unicode\u005E
. - Un accento grave (
`
) come rappresentato dall'espressione regolare Unicode\u0060
. - Una parentesi graffa aperta {
{
) come rappresentata dall'espressione regolare Unicode\u007B
. - Una parentesi graffa chiusa (
}
) come rappresentata dall'espressione regolare Unicode\u007D
. - Una tilde (
~
) come rappresentata dall'espressione regolare Unicode\u007E
.
Per linee guida aggiuntive, consulta Nomi delle colonne.
I caratteri delle colonne espansi sono supportati sia dall'API BigQuery Storage Read che dall'API BigQuery Storage Write. Per utilizzare l'elenco espanso di caratteri Unicode con l'API BigQuery Storage Read, devi impostare un flag. Puoi utilizzare l'attributo displayName
per recuperare il nome della colonna. L'esempio seguente mostra come impostare un flag con il client Python:
from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()
#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options
Per utilizzare l'elenco ampliato di caratteri Unicode con l'API BigQuery Storage Write, devi fornire lo schema con la notazione column_name
, a meno che non utilizzi l'oggetto writer JsonStreamWriter
. L'esempio seguente mostra come fornire
lo schema:
syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";
message FlexibleSchema {
optional string item_name_column = 1
[(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
optional string item_description_column = 2
[(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}
In questo esempio, item_name_column
e item_description_column
sono nomi segnaposto che devono essere conformi alla convenzione di denominazione per il buffer di protocollo. Tieni presente che le annotazioni column_name
hanno sempre la precedenza sui
nomi dei segnaposto.
- Per impostazione predefinita, il caricamento dei dati Parquet non supporta i nomi di colonna flessibili. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione nell'anteprima, eventuali nomi di colonna non validi (ad esempio la confronto dei nomi di colonna) restituiscono un errore. Per i progetti non registrati, la richiesta di caricamento sostituisce i caratteri non validi con trattini bassi anziché restituire un errore.
- Il caricamento dei dati CSV utilizzando il rilevamento automatico dello schema non supporta i nomi di colonna flessibili per impostazione predefinita. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione nell'anteprima, eventuali nomi di colonna non validi (ad esempio la confronto dei nomi di colonna) restituiscono un errore. Per i progetti non registrati, la richiesta di caricamento sostituisce i caratteri non validi con trattini bassi anziché restituire un errore.
I nomi di colonna flessibili non sono supportati con le tabelle esterne.
Non puoi caricare file Parquet contenenti colonne che hanno un punto (.) nel nome della colonna.
Se il nome di una colonna Parquet contiene altri caratteri (a parte il punto), i caratteri vengono sostituiti da trattini bassi. Puoi aggiungere trattini bassi finali
ai nomi delle colonne per evitare conflitti. Ad esempio, se un file Parquet contiene due
colonne Column1
e column1
, le colonne vengono caricate rispettivamente come Column1
e
column1_
.
Debug del file Parquet
Se i job di caricamento non superano gli errori relativi ai dati, puoi utilizzare PyArrow per verificare se i file di dati di Parquet sono danneggiati. Se PyArrow non riesce a leggere i file, è probabile che vengano rifiutati dal job di caricamento di BigQuery. L'esempio seguente mostra come leggere i contenuti di un file Parquet utilizzando PyFreccia:
from pyarrow import parquet as pq
# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
print col['column_path_in_schema']
print col['num_values']
Per ulteriori informazioni, consulta la documentazione di PyArrow.