Caricamento in batch dei dati mediante l'API Storage Write
Questo documento descrive come utilizzare l'API BigQuery Storage Write per caricare i dati in batch in BigQuery.
Negli scenari di caricamento batch, un'applicazione scrive i dati e li esegue il commit come singola transazione atomica. Quando utilizzi l'API Storage Write per caricare i dati in batch, crea uno o più flussi di tipo in attesa. Il tipo in attesa supporta le transazioni a livello di flusso. I record vengono memorizzati nel buffer in stato di attesa finché non esegui il commit del flusso.
Per i carichi di lavoro batch, puoi anche utilizzare l'API Storage Write tramite il connettore Apache Spark SQL per BigQuery con Dataproc, anziché scrivere codice API Storage Write personalizzato.
L'API Storage Write è particolarmente adatta per un'architettura di pipeline di dati. Un processo principale crea diversi flussi. Per ogni flusso, assegna un thread worker o un processo separato per scrivere una parte dei dati in batch. Ogni worker crea una connessione al proprio stream, scrive i dati e finalizza il flusso al termine dell'operazione. Dopo che tutti i worker segnalano il completamento del processo principale, il processo principale esegue il commit dei dati. In caso di errore, la parte dei dati assegnata non verrà mostrata nei risultati finali e l'intero worker può essere ritentato in sicurezza. In una pipeline più sofisticata, i worker controllano il loro avanzamento riportando l'ultimo offset scritto nel processo principale. Questo approccio può generare una pipeline solida e resiliente in caso di errori.
Carica in gruppo i dati utilizzando il tipo in attesa
Per utilizzare il tipo In attesa, l'applicazione esegue le seguenti operazioni:
- Chiama
CreateWriteStream
per creare uno o più stream di tipo in attesa. - Per ogni flusso, chiama
AppendRows
in un loop per scrivere batch di record. - Per ogni stream, chiama
FinalizeWriteStream
. Dopo aver chiamato questo metodo, non puoi scrivere altre righe nel flusso. Se chiamiAppendRows
dopo aver chiamatoFinalizeWriteStream
, viene restituito un valoreStorageError
conStorageErrorCode.STREAM_FINALIZED
nell'erroregoogle.rpc.Status
. Per saperne di più sul modello di erroregoogle.rpc.Status
, consulta Errori. - Chiama
BatchCommitWriteStreams
per eseguire il commit degli stream. Dopo aver chiamato questo metodo, i dati diventano disponibili per la lettura. Se si verifica un errore durante il commit di uno dei flussi, l'errore viene restituito nel campostream_errors
diBatchCommitWriteStreamsResponse
.
Il commit è un'operazione atomica e puoi eseguire il commit di più flussi contemporaneamente. È possibile eseguire il commit di un flusso solo una volta, quindi se l'operazione non riesce, puoi ritentare l'operazione in sicurezza. Finché non esegui il commit di un flusso, i dati restano in attesa e non sono visibili per le letture.
Dopo che il flusso è stato finalizzato e prima dell'esecuzione del commit, i dati possono rimanere nel buffer per un massimo di 4 ore. Il commit degli stream in attesa deve essere eseguito entro 24 ore. Esiste un limite di quota per la dimensione totale del buffer del flusso in attesa.
Il seguente codice mostra come scrivere dati in tipo In attesa:
C#
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Go
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. 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
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. 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
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Questo esempio mostra un record semplice con due campi. Per un esempio più lungo che mostra come inviare diversi tipi di dati, tra cui i tipi STRUCT
, consulta l'esempio di append_rows_proto2 su GitHub.
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. 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.
Questo esempio di codice dipende da un modulo di protocollo compilato, customer_record_pb2.py
. Per creare il modulo compilato, esegui protoc --python_out=. customer_record.proto
, dove protoc
è il compilatore del buffer di protocollo. Il file customer_record.proto
definisce il formato dei messaggi utilizzati nell'esempio Python.