Cargar datos por lotes con la API Storage Write
En este documento se describe cómo usar la API Storage Write de BigQuery para cargar datos por lotes en BigQuery.
En los casos de carga por lotes, una aplicación escribe datos y los confirma como una sola transacción atómica. Cuando uses la API Storage Write para cargar datos por lotes, crea una o varias transmisiones de tipo pendiente. El tipo pendiente admite transacciones a nivel de flujo. Los registros se almacenan en búfer en un estado pendiente hasta que confirmes el flujo.
En el caso de las cargas de trabajo por lotes, también puedes usar la API Storage Write a través del conector Apache Spark SQL para BigQuery con Dataproc, en lugar de escribir código personalizado de la API Storage Write.
La API Storage Write se adapta bien a una arquitectura de pipeline de datos. Un proceso principal crea varias emisiones. En cada flujo, se asigna un hilo de trabajo o un proceso independiente para escribir una parte de los datos del lote. Cada trabajador crea una conexión con su flujo, escribe datos y finaliza su flujo cuando termina. Una vez que todos los trabajadores hayan indicado que se ha completado correctamente al proceso principal, este confirmará los datos. Si un trabajador falla, la parte de los datos que se le haya asignado no se mostrará en los resultados finales y se podrá volver a intentar con todo el trabajador sin problemas. En una canalización más sofisticada, los trabajadores registran su progreso informando del último desplazamiento escrito en el proceso principal. Este enfoque puede dar lugar a una canalización sólida que sea resistente a los fallos.
Cargar datos por lotes mediante el tipo pendiente
Para usar el tipo pendiente, la aplicación hace lo siguiente:
- Llama a
CreateWriteStream
para crear una o varias secuencias de tipo pendiente. - En cada flujo, llama a
AppendRows
en un bucle para escribir lotes de registros. - En cada flujo, llama a
FinalizeWriteStream
. Después de llamar a este método, no podrás escribir más filas en el flujo. Si llamas aAppendRows
después de llamar aFinalizeWriteStream
, se devuelve unStorageError
conStorageErrorCode.STREAM_FINALIZED
en el errorgoogle.rpc.Status
. Para obtener más información sobre el modelo de erroresgoogle.rpc.Status
, consulta la sección Errores. - Llama a
BatchCommitWriteStreams
para confirmar las transmisiones. Después de llamar a este método, los datos estarán disponibles para su lectura. Si se produce un error al confirmar alguna de las emisiones, se devuelve en el campostream_errors
delBatchCommitWriteStreamsResponse
.
La confirmación es una operación atómica y puedes confirmar varias secuencias a la vez. Una emisión solo se puede confirmar una vez, por lo que, si la operación de confirmación falla, se puede volver a intentar. Hasta que confirmes un flujo, los datos estarán pendientes y no se podrán leer.
Una vez que se ha finalizado el flujo y antes de que se confirme, los datos pueden permanecer en el búfer hasta 4 horas. Las emisiones pendientes deben confirmarse en un plazo de 24 horas. Hay un límite de cuota en el tamaño total del búfer de la emisión pendiente.
En el siguiente código se muestra cómo escribir datos de tipo pendiente:
C#
Para saber cómo instalar y usar la biblioteca de cliente de BigQuery, consulta Bibliotecas de cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API C# de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Go
Para saber cómo instalar y usar la biblioteca de cliente de BigQuery, consulta Bibliotecas de cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Java
Para saber cómo instalar y usar la biblioteca de cliente de BigQuery, consulta Bibliotecas de cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Node.js
Para saber cómo instalar y usar la biblioteca de cliente de BigQuery, consulta Bibliotecas de cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Python
En este ejemplo se muestra un registro sencillo con dos campos. Para ver un ejemplo más extenso que muestra cómo enviar diferentes tipos de datos, incluidos los tipos STRUCT
, consulta el ejemplo append_rows_proto2 en GitHub.
Para saber cómo instalar y usar la biblioteca de cliente de BigQuery, consulta Bibliotecas de cliente de BigQuery. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Este ejemplo de código depende de un módulo de protocolo compilado, customer_record_pb2.py
. Para crear el módulo compilado, ejecuta protoc --python_out=. customer_record.proto
, donde protoc
es el compilador de búfer de protocolo. El archivo customer_record.proto
define el formato de los mensajes utilizados en el ejemplo de Python.