Carregar dados em lote usando a API StorageWrite
Neste documento, descrevemos como usar a API BigQuery Storage Write para carregar dados em lote no BigQuery.
Em cenários de carregamento em lote, um aplicativo grava dados e os confirma como uma única transação atômica. Ao usar a API StorageWrite para carregar dados em lote, crie um ou mais streams no modo pendente. O tipo pendente é compatível com transações no nível de stream. Os registros são armazenados em buffer em um estado pendente até que você confirme o stream.
Para cargas de trabalho em lote, também considere usar a API StorageWrite por meio do conector de SQL do Apache Spark para BigQuery usando o Dataproc, em vez de escrever um código personalizado da API StorageWrite.
A API StorageWrite é adequada para a arquitetura de pipeline de dados. Um processo principal cria vários streams. Para cada fluxo, ele atribui uma linha de execução de worker ou um processo separado para gravar uma parte dos dados em lote. Cada worker cria uma conexão com o stream, grava dados e finaliza o stream quando ele é concluído. Depois que todos os workers sinalizam a conclusão bem-sucedida do processo principal, o processo principal confirma os dados. Se um worker falhar, a parte atribuída dos dados não vai aparecer nos resultados finais, e o worker inteiro pode ser repetido com segurança. Em um pipeline mais sofisticado, os workers verificam o progresso informando o último deslocamento gravado no processo principal. Essa abordagem pode resultar em um pipeline robusto que é resistente a falhas.
Carregar dados em lote usando o tipo pendente
Para usar o modo pendente, o aplicativo realiza as seguintes ações:
- Chame
CreateWriteStream
para criar um ou mais streams no modo pendente. - Para cada stream, chame
AppendRows
em um loop para gravar lotes de registros. - Para cada stream, chame
FinalizeWriteStream
. Depois de chamar esse método, não será possível gravar mais linhas no stream. Se você chamarAppendRows
depois de chamarFinalizeWriteStream
, ele retornará umStorageError
comStorageErrorCode.STREAM_FINALIZED
no errogoogle.rpc.Status
. Para mais informações sobre o modelo de errogoogle.rpc.Status
, consulte Erros. - Chame
BatchCommitWriteStreams
para confirmar os streams. Depois de chamar esse método, os dados estarão disponíveis para leitura. Se ocorrer um erro na confirmação de qualquer um dos streams, ele será retornado no campostream_errors
doBatchCommitWriteStreamsResponse
.
A confirmação é uma operação atômica e é possível confirmar vários fluxos de uma só vez. Um stream só pode ser confirmado uma vez. Portanto, se a operação de confirmação falhar, é seguro repeti-lo. Até a confirmação de um stream, os dados ficam pendentes e não visíveis para leituras.
Depois que o stream é finalizado e antes de ser confirmado, os dados podem permanecer no buffer por até quatro horas. Os streams pendentes precisam ser confirmados em até 24 horas. Há um limite de cota no tamanho total do buffer de stream pendente.
O código a seguir mostra como gravar dados no modo pendente.
C#
Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery C#.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Go
Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Go.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Java
Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Java.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Node.js
Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Python
Neste exemplo, mostramos um
registro simples com dois campos. Para ver um exemplo mais longo que
mostra como enviar diferentes tipos de dados, incluindo tipos STRUCT
, consulte a
amostra append_rows_proto2 no GitHub.
Para saber como instalar e usar a biblioteca de cliente do BigQuery, consulte Bibliotecas do cliente do BigQuery. Para mais informações, consulte a documentação de referência da API BigQuery Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
O exemplo de código depende de um módulo de protocolo compilado,
customer_record_pb2.py
. Para criar o módulo compilado, execute
protoc --python_out=. customer_record.proto
, em que protoc
é o
compilador de buffer de protocolo. O arquivo customer_record.proto
define o formato
das mensagens usadas no exemplo do Python.