Carica in batch i dati utilizzando l'API Storage Write
Questo documento descrive come utilizzare l'API BigQuery Storage Write per caricare in batch i dati 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 il caricamento batch dei dati, crea uno o più stream di tipo in attesa. Il tipo In attesa supporta le transazioni a livello di stream. I record vengono memorizzati nel buffer in stato in attesa finché non esegui il commit dello stream.
Per i carichi di lavoro batch, valuta anche l'utilizzo dell'API Storage Write tramite il connettore Apache Spark SQL per BigQuery utilizzando Dataproc, anziché scrivere codice personalizzato per l'API Storage Write.
L'API Storage Write è adatta a un'architettura di pipeline di dati. Un processo principale crea una serie di stream. Per ogni flusso, assegna un thread worker o un processo separato per scrivere una parte dei dati batch. Ogni worker crea una connessione al proprio stream, scrive i dati e finalizza lo stream al termine dell'operazione. Dopo che tutti i worker segnalano il completamento al processo principale, quest'ultimo esegue il commit dei dati. Se un worker non riesce, la parte assegnata dei dati non verrà visualizzata nei risultati finali e l'intero worker può essere riprovato in modo sicuro. In una pipeline più sofisticata, i worker controllano i progressi segnalando l'ultimo offset scritto al processo principale. Questo approccio può portare a una pipeline solida e resiliente agli errori.
Caricare i dati in batch utilizzando il tipo in attesa
Per utilizzare il tipo in attesa, l'applicazione esegue le operazioni seguenti:
- Chiama
CreateWriteStream
per creare uno o più stream di tipo in attesa. - Per ogni stream, chiama
AppendRows
in un ciclo 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 unStorageError
conStorageErrorCode.STREAM_FINALIZED
nell'erroregoogle.rpc.Status
. Per saperne di più sul modello di erroregoogle.rpc.Status
, vedi 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 degli stream, l'errore viene restituito nel campostream_errors
diBatchCommitWriteStreamsResponse
.
Il commit è un'operazione atomica e puoi eseguire il commit di più stream contemporaneamente. Un flusso può essere sottoposto a commit una sola volta, quindi se l'operazione di commit non va a buon fine, è sicuro riprovare. Finché non esegui il commit di uno stream, i dati sono in attesa e non visibili alle letture.
Dopo la finalizzazione e prima del commit, i dati possono rimanere nel buffer fino a 4 ore. Gli stream in attesa devono essere confermati entro 24 ore. Esiste un limite di quota per le dimensioni totali del buffer di stream in attesa.
Il seguente codice mostra come scrivere i dati nel tipo in attesa:
C#
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Vai
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi 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 ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi 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 ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Python
Questo esempio mostra un semplice record con due campi. Per un esempio più lungo che
mostra come inviare diversi tipi di dati, inclusi i tipi STRUCT
, consulta l'esempio append_rows_proto2 su GitHub.
Per scoprire come installare e utilizzare la libreria client per BigQuery, consulta Librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi 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 del protocollo. Il file customer_record.proto
definisce il formato
dei messaggi utilizzati nell'esempio Python.