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 nel dell'ecosistema Apache Hadoop.
Quando carichi dati Parquet da Cloud Storage, puoi caricarli in un nuova tabella o partizione oppure puoi aggiungere o sovrascrivere una tabella o della partizione di testo. Quando i dati vengono caricati in BigQuery, convertito in formato a colonne per Condensatore (formato di archiviazione di BigQuery).
Quando carichi i dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa regione regionale come bucket Cloud Storage.
Per informazioni sul caricamento dei dati Parquet da un file locale, vedi Caricamento di dati da file locali.
Limitazioni
Quando carichi dati in: BigQuery da un bucket Cloud Storage:
- Se la località del set di dati è impostata su un valore diverso dall'area multiregionale
US
, il bucket Cloud Storage deve trovarsi nella stessa regione o contenuto nella stessa località (multiregionale) del set di dati. - BigQuery non garantisce la coerenza dei dati esterni fonti. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono comportare comportamenti imprevisti.
BigQuery non supporta Controllo delle versioni degli oggetti Cloud Storage. Se includi un numero di generazione nell'URI di Cloud Storage, il job di caricamento non riesce.
Il caricamento dei dati Parquet segue convenzione di denominazione delle colonne e non Supportare nomi di colonna flessibili per impostazione predefinita. Per iscriverti a questa anteprima, completa la modulo di registrazione.
Non puoi utilizzare un carattere jolly nell'URI di Cloud Storage se uno dei file da caricare hanno schemi diversi. Qualsiasi differenza nella posizione le colonne vengono considerate uno schema diverso.
Requisiti del file di input
Per evitare resourcesExceeded
errori durante il caricamento dei file Parquet in
BigQuery, segui queste linee guida:
- Mantieni le dimensioni delle righe fino a 50 MB o inferiori.
- Se i dati di input contengono più di 100 colonne, valuta la possibilità di ridurre la pagina inferiore a quello predefinito della pagina (1 * 1024 * 1024 byte). Questo è particolarmente utile se utilizzi una compressione significativa.
Prima di iniziare
Concedi ruoli IAM (Identity and Access Management) che concedono agli utenti le risorse necessarie autorizzazioni per eseguire ogni attività in questo documento e creare per archiviare i dati.
Autorizzazioni obbligatorie
Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati nelle tabelle e nelle partizioni BigQuery. Se carichi dati da Cloud Storage, devi disporre anche delle autorizzazioni IAM per accedere al bucket che contiene i 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 una 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, vedi 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
Ruolo IAM Storage Admin (roles/storage.admin
) nel 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 vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:
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 riuscire a ottenere queste autorizzazioni con ruoli personalizzati altri ruoli predefiniti.
Crea un set di dati
Crea un set di dati BigQuery per archiviare i tuoi dati.
Schemi Parquet
Quando carichi file Parquet in BigQuery, lo schema della tabella viene automaticamente dai dati di origine autodescrittivi. 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 carica 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 specificate in più schemi devono avere la stessa modalità in ogni definizione dello schema.
Quando BigQuery rileva lo schema, alcuni tipi di dati Parquet vengono convertiti in tipi di dati BigQuery per renderli compatibili Sintassi GoogleSQL. Per ulteriori informazioni, vedi Conversioni di Parquet.
Per fornire uno schema per la creazione di tabelle esterne, impostareferenceFileSchemaUri
nell'API BigQuery o il parametro --reference_file_schema_uri
nello strumento a riga di comando bq
all'URL del file di riferimento.
Ad esempio, --reference_file_schema_uri="gs://mybucket/schema.parquet"
.
Compressione Parquet
BigQuery supporta i seguenti codec di compressione Contenuti del 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 in uno dei seguenti modi:
- Nella console Google Cloud
- Il comando
bq load
dello strumento a riga di comando bq - Il metodo API
jobs.insert
e la configurazione di un jobload
- Le librerie client
Caricare dati Parquet da Cloud Storage in un nuovo BigQuery tabella:
Console
Nella console Google Cloud, vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto e 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 segui questi passaggi:
- Seleziona un file dal bucket Cloud Storage o inserisci URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma con i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nello stesso posizione come il set di dati che contiene la tabella da creare, aggiungere o sovrascrivere.
- In Formato file, seleziona Pacchino.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- In Set di dati, seleziona il set di dati in cui creare il tabella.
- Nel campo Tabella, inserisci il nome della tabella da creare.
- Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
- Nella sezione Schema non è necessaria alcuna azione. Lo schema è che si autodefinisce nei file Parquet.
- (Facoltativo) Specifica le impostazioni di partizione e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
- Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
- In Write preference (Preferenza di scrittura), lascia selezionata l'opzione Write if empty (Scrivi se vuoto). Questo crea una nuova tabella e carica i dati al suo interno.
- Se vuoi ignorare i valori in una riga 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 la
LOAD DATA
Istruzione DDL.
L'esempio seguente carica 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
Usa il comando bq load
e specifica PARQUET
tramite --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 carattere jolly.
(Facoltativo) Fornisci il flag --location
e imposta il valore su
località.
Altri flag facoltativi includono:
--time_partitioning_type
: abilita il partizionamento in base al tempo in una tabella e imposta il tipo di partizione. I valori possibili sonoHOUR
,DAY
,MONTH
, eYEAR
. Questo flag è facoltativo quando crei partizionata in base a una colonnaDATE
,DATETIME
oTIMESTAMP
. La il tipo di partizione predefinito per il partizionamento basato sul tempo èDAY
. Non puoi modificare la specifica di partizionamento su una tabella esistente.--time_partitioning_expiration
: un numero intero che specifica (in secondi) quando occorre eliminare una partizione temporale. Data e ora di scadenza restituisce la data UTC della partizione più il valore intero.--time_partitioning_field
: la colonnaDATE
oTIMESTAMP
utilizzata per una tabella partizionata. Se il partizionamento basato sul tempo è abilitato senza viene creata una tabella partizionata per data di importazione.--require_partition_filter
: quando è abilitata, questa opzione richiede agli utenti per 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, vedi Esecuzione di query su 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 file e i dati della tabella.--column_name_character_map
: definisce l'ambito e la gestione dei nei nomi delle colonne, con l'opzione di abilitare nomi di colonne flessibili. Per ulteriori informazioni, vediload_option_list
Per saperne di più sulle tabelle partizionate, consulta:
Per ulteriori informazioni sulle tabelle in cluster, consulta:
Per ulteriori informazioni sulla crittografia delle tabelle, consulta:
Per caricare i dati Parquet in BigQuery, inserisci il comando seguente:
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 Regione di Tokyo, puoi impostare il valore del flag suasia-northeast1
. Puoi imposta un valore predefinito per la località utilizzando file.bigqueryrc.FORMAT
:PARQUET
.DATASET
: un set di dati esistente.TABLE
: il nome della tabella in cui ti trovi caricare i dati.PATH_TO_SOURCE
: un nome completo URI Cloud Storage oppure un elenco di URI separati da virgole. Caratteri jolly sono supportate.
Esempi:
Il seguente comando carica i dati da gs://mybucket/mydata.parquet
in un
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 un
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 un
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 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 dati da più file in gs://mybucket/
in una tabella denominata mytable
in mydataset
. Il comando include una virgola
elenco separato di URI di 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 punti ai dati di origine in Cloud Storage.(Facoltativo) Specifica la tua località in la proprietà
location
nella sezionejobReference
della risorsa job.La proprietà
source URIs
deve essere completa, nel formatogs://BUCKET/OBJECT
. Ogni URI può contenere un carattere "*" carattere jolly.Specifica il formato dei dati Parquet impostando la proprietà
sourceFormat
suPARQUET
.Per controllare lo stato del lavoro, chiama
jobs.get(JOB_ID*)
, sostituendo JOB_ID con l'ID del job restituito dal richiesta.- Se
status.state = DONE
, il job è stato completato correttamente. - Se è presente la proprietà
status.errorResult
, la richiesta non è riuscita. e include informazioni che descrivono cosa non ha funzionato. 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 importando alcune righe. Gli errori non irreversibili sono elencati nel job restituito dell'oggettostatus.errors
.
- Se
Note API:
I job di caricamento sono atomici e coerenti: se un job di caricamento non riesce, nessuno dei dati e, se un job di caricamento ha esito positivo, saranno disponibili tutti i dati.
Come best practice, genera un ID univoco e passalo come
jobReference.jobId
durante la chiamata ajobs.insert
per creare un job di caricamento. Questo è più efficace per gli errori di rete perché il client può eseguire il polling o riprova sull'ID job noto.Chiamare
jobs.insert
su un determinato ID job è idempotente. Puoi riprovare come tutte le volte che desideri per lo stesso ID job e al massimo una di queste operazioni avranno esito positivo.
Vai
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
PHP
Prima di provare questo esempio, segui le istruzioni per la configurazione di PHP nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API PHP BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Utilizza la Client.load_table_from_uri() per avviare un job di caricamento da Cloud Storage. Per usare Parquet, imposta il valore LoadJobConfig.source_format proprietà alla stringaPARQUET
e passa la configurazione del job come
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 quale azione eseguire quando carichi i dati da un file di origine o da una query o il risultato finale.
Quando carichi dati aggiuntivi in una tabella, hai a disposizione le seguenti opzioni:
Opzione della console | flag strumento bq | Proprietà API BigQuery | Descrizione |
---|---|---|---|
Scrivi se vuota | 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 |
(valore predefinito) Aggiunge 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 i nuovi dati. Questa azione elimina anche lo schema della tabella, la sicurezza a livello di riga e rimuove eventuali 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 elementi:
- Nella console Google Cloud
- Il comando
bq load
dello strumento a riga di comando bq - Il metodo API
jobs.insert
e la 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 e 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 segui questi passaggi:
- Seleziona un file dal bucket Cloud Storage o inserisci URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma con i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nello stesso posizione come il set di dati che contiene la tabella da creare, aggiungere o sovrascrivere.
- In Formato file, seleziona Pacchino.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- In Set di dati, seleziona il set di dati in cui creare il tabella.
- Nel campo Tabella, inserisci il nome della tabella da creare.
- Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
- Nella sezione Schema non è necessaria alcuna azione. Lo schema è che si autodefinisce nei file Parquet.
- (Facoltativo) Specifica le impostazioni di partizione e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster. Tu impossibile convertire una tabella in una tabella partizionata o in cluster aggiungendo o sovrascriverlo. La console Google Cloud non supporta aggiungendo o sovrascrivendo 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 dalla tabella.
- Se vuoi ignorare i valori in una riga 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 la
LOAD DATA
Istruzione DDL.
Nell'esempio seguente, un file Parquet viene aggiunto 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
tabella. Utilizza il flag --noreplace
per aggiungere dati alla tabella. Se non è presente alcun flag
specificato, il valore predefinito è l'aggiunta di dati. Fornisci il flag --source_format
e lo imposti su PARQUET
. Perché gli schemi Parquet vengono recuperati automaticamente
dai dati di origine autodescrittivi, non è necessario fornire uno schema
definizione di Kubernetes.
(Facoltativo) Fornisci il flag --location
e imposta il valore su
località.
Altri flag facoltativi includono:
--destination_kms_key
: la chiave Cloud KMS per la crittografia dei file e i 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 posizione utilizzando file.bigqueryrc.format
:PARQUET
.dataset
: un set di dati esistente.table
: il nome della tabella in cui ti trovi caricare i dati.path_to_source
: un nome completo URI Cloud Storage oppure un elenco di URI separati da virgole. Caratteri jolly sono supportate.
Esempi:
Il comando seguente 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 comando seguente carica i dati da gs://mybucket/mydata.parquet
e
accoda dati a una tabella denominata mytable
in mydataset
.
bq load \
--noreplace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
Per informazioni sull'aggiunta e la sovrascrittura delle tabelle partizionate mediante a riga di comando bq, consulta Aggiunta e sovrascrittura di tabella partizionata partizionate.
API
Crea un job
load
che punti ai dati di origine in Cloud Storage.(Facoltativo) Specifica la tua località in la proprietà
location
nella sezionejobReference
della risorsa job.La proprietà
source URIs
devono essere completi, nel formatogs://BUCKET/OBJECT
. Puoi Includere più URI sotto forma di elenco separato da virgole. Tieni presente che caratteri jolly sono .Specifica il formato dei dati impostando il parametro
configuration.load.sourceFormat
aPARQUET
.Specifica la preferenza di scrittura impostando il parametro
configuration.load.writeDisposition
proprietà aWRITE_TRUNCATE
oWRITE_APPEND
.
Vai
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
PHP
Prima di provare questo esempio, segui le istruzioni per la configurazione di PHP nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API PHP BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Per sostituire le righe in una tabella esistente, imposta LoadJobConfig.write_disposition proprietà al WRITE_TRUNCATE.Caricamento dei dati Parquet partizionati in hive
BigQuery supporta il caricamento di dati Parquet partizionati hive archiviati su Cloud Storage e compila le colonne di partizionamento hive come colonne in nella tabella gestita da BigQuery di destinazione. Per ulteriori informazioni, vedi Caricamento di dati partizionati esternamente.
Conversioni Parquet
Questa sezione descrive come BigQuery analizza i vari tipi di dati durante il caricamento dei dati Parquet.
Alcuni tipi di dati Parquet (come 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 nel Tipi di dati di BigQuery descritti nelle sezioni seguenti.
Conversioni dei tipi
Tipo di dati BigQuery | ||
---|---|---|
BOOLEAN |
Nessuno | 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 e precision=MILLIS
(TIMESTAMP_MILLIS )
|
TIMESTAMP |
INT64 |
TIMESTAMP e precision=MICROS
(TIMESTAMP_MICROS )
|
TIMESTAMP |
INT96 |
Nessuno | TIMESTAMP |
FLOAT |
Nessuno | FLOAT64 |
DOUBLE |
Nessuno | FLOAT64 |
BYTE_ARRAY |
Nessuno | BYTES |
BYTE_ARRAY |
STRING (UTF8 ) |
STRINGA |
FIXED_LEN_BYTE_ARRAY | DECIMALE | NUMERIC, BIGNUMERIC o STRING |
FIXED_LEN_BYTE_ARRAY |
Nessuno | BYTES |
I gruppi nidificati vengono convertiti in
STRUCT
.
Non sono supportate altre combinazioni di tipi Parquet e tipi convertiti.
Tipi logici non firmati
I tipi 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 un
Colonna INTEGER
firmata da BigQuery. Nel caso di UINT_64
, verrà restituito un errore
Se il valore non firmato supera il valore massimo di INTEGER
di
9.223.372.036.854.775.807.
Tipo logico decimale
Decimal
tipi logici possono essere convertiti in NUMERIC
, BIGNUMERIC
o STRING
tipi. Il tipo convertito dipende
sui parametri di precisione e scala del tipo logico decimal
e
tipi di target decimali specificati. Specifica il tipo di target decimale come segue:
- Per un job di caricamento utilizzando la proprietà
API
jobs.insert
: utilizzaJobConfigurationLoad.decimalTargetTypes
. - Per un job di caricamento utilizzando la proprietà
bq load
nello strumento a riga di comando bq: usa--decimal_target_types
flag. - Per una query su una tabella con origini esterne:
usa
ExternalDataConfiguration.decimalTargetTypes
. - Per una tabella esterna permanente creata con 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 utilizzando la proprietà
API
jobs.insert
: utilizzaJobConfigurationLoad.parquetOptions
. - Per un job di caricamento utilizzando la proprietà
bq load
nello strumento a riga di comando bq: 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
si trova
formato standard o in uno dei formati descritti dalle regole di compatibilità con le versioni precedenti:
// standard form
<optional | required> group <name> (LIST) {
repeated group list {
<optional | required> <element-type> element;
}
}
Se sì, il campo corrispondente per il nodo LIST
nello schema convertito viene trattato
come se il nodo avesse il seguente schema:
repeated <element-type> <name>
L'elenco dei nodi e "elemento" vengono omessi.
- Per un job di caricamento utilizzando la proprietà
API
jobs.insert
: utilizzaJobConfigurationLoad.parquetOptions
. - Per un job di caricamento utilizzando la proprietà
bq load
nello strumento a riga di comando bq: 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 i file Parquet che contengono WKT, WKB con codifica esadecimale o GeoJSON in un
STRING
o WKB in una colonna BYTE_ARRAY
specificando un
Schema di BigQuery di tipo GEOGRAPHY
. Consulta la sezione Caricamento di dati geospaziali
Dati.
Conversioni dei nomi di 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 la colonna flessibile , BigQuery supporta l'inizio del nome della colonna con un numero. Presta attenzione quando inizi colonne con un numero, poiché utilizzi l'impostazione i nomi delle colonne con l'API BigQuery Storage Read o L'API BigQuery StorageWrite richiede una gestione speciale. Per ulteriori informazioni supporto flessibile per nomi di colonna, consulta nomi di colonne flessibili.
I nomi delle colonne hanno 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 l'uso delle maiuscole e delle minuscole è diverso. Ad esempio, un
una colonna denominata Column1
è considerata identica a una colonna denominata column1
. A
per ulteriori informazioni sulle regole di denominazione delle colonne, consulta Colonna
nomi utente nel
Riferimento GoogleSQL.
Se il nome di una tabella (ad esempio test
) corrisponde al nome di una delle sue colonne
(ad esempio, test
), l'espressione SELECT
interpreta la colonna test
come
un STRUCT
contenente tutte le altre colonne della tabella. Per evitare questa collisione, utilizza
uno dei seguenti metodi:
Evita di utilizzare lo stesso nome per una tabella e le sue colonne.
Assegna alla tabella un alias diverso. Ad esempio, la seguente query assegna un alias di tabella
t
per la 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à nel assegnare un nome alle colonne, incluso l'accesso esteso ai caratteri in lingue diverse dall'inglese nonché a simboli aggiuntivi.
I nomi delle colonne flessibili supportano i seguenti caratteri:
- Qualsiasi lettera in qualsiasi lingua, rappresentata dall'espressione regolare Unicode
\p{L}
- Qualsiasi carattere numerico in qualsiasi lingua, come rappresentato dalla regola Unicode
espressione
\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 rappresentato dall'espressione regolare Unicode.
\p{Pd}
- Qualsiasi marchio destinato ad accompagnare un altro carattere, come rappresentato dal
Espressione regolare Unicode
\p{M}
Ad esempio, accenti, dieresi o contenuti che includono riquadri. - I seguenti caratteri speciali:
- Una e commerciale (
&
) rappresentata dalla regola Unicode dell'espressione\u0026
. - Un segno di percentuale (
%
) come rappresentato dalla regola Unicode dell'espressione\u0025
. - Un segno di uguale (
=
) come rappresentato dalla regola Unicode dell'espressione\u003D
. - Un segno più (
+
) come rappresentato dalla regola Unicode dell'espressione\u002B
. - I due punti (
:
) come rappresentati dalla regola Unicode dell'espressione\u003A
. - Un apostrofo (
'
) come rappresentato dalla regola Unicode dell'espressione\u0027
. - Un segno di minore (
<
) rappresentato dalla regola Unicode dell'espressione\u003C
. - Un segno di maggiore (
>
) rappresentato dalla regola Unicode dell'espressione\u003E
. - Un segno numerico (
#
) come rappresentato dalla regola Unicode dell'espressione\u0023
. - Una linea verticale (
|
) rappresentata dalla barra Unicode regolare dell'espressione\u007c
. - Spazio vuoto.
- Una e commerciale (
I nomi delle colonne flessibili non supportano i seguenti caratteri speciali:
- Un punto esclamativo (
!
) come rappresentato dal simbolo Unicode dell'espressione\u0021
. - Una virgoletta (
"
) rappresentata dalla regola Unicode dell'espressione\u0022
. - Un simbolo del dollaro (
$
) rappresentato dalla regola Unicode dell'espressione\u0024
. - Una parentesi aperta (
(
) rappresentata dalla regolare Unicode dell'espressione\u0028
. - Una parentesi chiusa (
)
) rappresentata dalla regolare Unicode dell'espressione\u0029
. - Un asterisco (
*
) come rappresentato dalla regola Unicode dell'espressione\u002A
. - Una virgola (
,
) come rappresentata dal valore regolare Unicode dell'espressione\u002C
. - Un punto (
.
) come rappresentato dalla regola Unicode dell'espressione\u002E
. - Una barra (
/
) rappresentata dalla barra Unicode regolare dell'espressione\u002F
. - Un punto e virgola (
;
) come rappresentato dalla regola Unicode dell'espressione\u003B
. - Un punto interrogativo (
?
) come rappresentato dalla regola Unicode dell'espressione\u003F
. - Una chiocciola (
@
) come rappresentata dalla forma regolare Unicode dell'espressione\u0040
. - Una parentesi quadra aperta (
[
) rappresentata dalla barra Unicode regolare dell'espressione\u005B
. - Una barra rovesciata (
\
) rappresentata dalla barra Unicode regolare dell'espressione\u005C
. - Una parentesi quadra chiusa (
]
) rappresentata dalla barra Unicode regolare dell'espressione\u005D
. - Un accento circonflesso (
^
) come rappresentato dalla regolare Unicode dell'espressione\u005E
. - Un accento grave (
`
) come rappresentato dalla regola Unicode dell'espressione\u0060
. - Una parentesi graffa aperta {
{
) rappresentata dalla regola Unicode dell'espressione\u007B
. - Una parentesi graffa chiusa (
}
) rappresentata dalla regola Unicode dell'espressione\u007D
. - Una tilde (
~
) rappresentata dall'espressione regolare Unicode\u007E
.
Per ulteriori linee guida, vedi Nomi delle colonne.
I caratteri della colonna espansi sono supportati dall'API BigQuery Storage Read
e l'API BigQuery StorageWrite. Per utilizzare l'elenco espanso di caratteri Unicode
con l'API BigQuery Storage Read, devi impostare un flag. Puoi utilizzare lo
displayName
per recuperare il nome della colonna. Nell'esempio che segue
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 usare l'elenco espanso di caratteri Unicode con l'API BigQuery StorageWrite,
devi fornire lo schema con la notazione column_name
, a meno che non utilizzi
l'oggetto writer JsonStreamWriter
. L'esempio seguente mostra come
indica 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 alle
denominazione del buffer di protocollo
convenzione. Tieni presente che le annotazioni column_name
hanno sempre la precedenza sulle
i nomi dei segnaposto.
- Il caricamento dei dati Parquet non supporta nomi di colonne flessibili per impostazione predefinita. Per iscriverti a questa anteprima, completa la modulo di registrazione. Tieni presente che dopo la registrazione all'anteprima, eventuali nomi di colonna non validi (ad esempio, le regole di 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 che restituisce un errore.
- Caricamento dei dati CSV utilizzando il rilevamento automatico dello schema non supporta nomi di colonne flessibili per impostazione predefinita. Per iscriverti a questa anteprima, completa la modulo di registrazione. Tieni presente che, dopo la registrazione all'anteprima, eventuali nomi di colonna non validi (ad esempio, regole di confronto dei nomi di colonna) restituiscono un errore. Per i progetti non registrata, la richiesta di caricamento sostituisce i caratteri non validi con trattini bassi anziché restituire un errore.
Limitazioni
I nomi delle colonne flessibili hanno un supporto limitato per le tabelle esterne. Colonna flessibile sono supportati solo per le tabelle Apache Iceberg e Delta Lake con colonna la mappatura dei nomi abilitata. Non sono supportate per altre tabelle esterne.
Non puoi caricare file Parquet contenenti colonne con un punto (.) nel nome della colonna.
Se il nome di una colonna Parquet contiene altri caratteri (a parte il punto), il parametro
vengono sostituiti con trattini bassi. Puoi aggiungere trattini bassi finali
i nomi delle colonne per evitare collisioni. Ad esempio, se un file Parquet contiene 2
colonne Column1
e column1
, le colonne vengono caricate come Column1
e
rispettivamente column1_
.
Debug del file Parquet
Se i job di caricamento hanno esito negativo e errori relativi ai dati, puoi utilizzare PyArrow per verificare se le tue I file di dati Parquet sono danneggiati. Se PyArrow non riesce a leggere i file, questi ultimi verranno probabilmente rifiutati dal job di caricamento BigQuery. Le seguenti esempio mostra come leggere i contenuti di un file Parquet utilizzando PyArrow:
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.