Tipos de mensajes

Cuando ingires con los SDKs de Ingesta de Zerobus sobre gRPC, eliges cómo se codifican los registros en un flujo dado. Zerobus Ingest soporta tres formatos de mensaje (JSON, Protocol Buffers (protobuf) y Apache Arrow), por lo que puedes alternar sencillez, seguridad de tipos y rendimiento para tu carga de trabajo. Cada formato se valida contra el esquema de tu tabla Delta antes de que los datos se vuelvan duraderos. Consulta Gestión de esquemas.

Los mismos 1.000 registros en tres formatos de mensaje: protobuf como una codificación compacta y tipada de filas, Apache Arrow como un lote columnar cuyos metadatos y búferes se reparten entre todo el lote, y JSON como texto legible con nombres de campos repetidos

¿Qué formato deberías usar?

Formato Más adecuado para Notas
JSON Primeros pasos y productores simples. La opción más sencilla, sin necesidad de compilar una definición de esquema. Conveniente, pero más lento que los formatos binarios para cargas de trabajo de alto volumen.
Búferes de protocolo De producción, flujos de alto volumen orientados a filas. Codificación binaria compacta con seguridad de tipos. Recomendado para la mayoría de cargas de producción. Requiere un esquema compilado.
Flecha Apache Cargas de trabajo columnares o orientadas a lotes. Envía lotes de registros Apache Arrow directamente, evitando la serialización fila por fila. Es mejor cuando tus datos ya son columnares o los ingieres en lotes. Consulte Usar Arrow Flight con Zerobus Ingest.

Los fragmentos a continuación muestran la forma de cada formato en el SDK de Python. Asumen que ya has creado el cliente SDK y conoces tu tabla objetivo. Para la configuración completa (endpoint, tabla, principal de servicio) y ejemplos en cada lenguaje, véase Use Zerobus Ingest.

JSON

JSON es la forma más sencilla de empezar: envías registros como objetos JSON sin definición de esquema para compilar. Es ideal para ponerse en marcha, prototipar y producir donde la comodidad importa más que el rendimiento bruto. Para cargas de producción de alto volumen, un formato binario (protobuf o Arrow) es más eficiente.

Crea un flujo para registros JSON pasando un nombre de tabla a TableProperties sin descriptor:

table_properties = TableProperties(TABLE_NAME)
stream = sdk.create_stream(CLIENT_ID, CLIENT_SECRET, table_properties)

stream.ingest_record_offset({"device_name": "sensor-1", "temp": 22, "humidity": 55})

Para ver la guía completa en JSON, véase Escribe un cliente.

Búferes de protocolo

Protobuf proporciona una codificación binaria compacta con seguridad de tipos y es el formato recomendado para la mayoría de las cargas de trabajo de producción basadas en filas. Defines un esquema protobuf que se ajusta a tu tabla Delta objetivo (ver esquema Protobuf), lo compilas y el SDK ingiere registros registro por registro sobre gRPC.

Usar protobuf requiere tres pasos: generar un .proto esquema que coincida con tu tabla, compilarlo en un módulo de lenguaje y luego ingerir registros pasando el descriptor a TableProperties. El siguiente ejemplo utiliza el SDK de Python.

1. Genera un .proto esquema a partir de tu tabla. El SDK de Python incluye una generate_proto herramienta que lee tu tabla Delta y escribe un esquema coincidente:

python -m zerobus.tools.generate_proto \
    --uc-endpoint "https://<workspace-id>.cloud.databricks.com" \
    --client-id "<client-id>" \
    --client-secret "<client-secret>" \
    --table "main.default.air_quality" \
    --output "record.proto" \
    --proto-msg "AirQuality"

El esquema generado utiliza proto2 sintaxis, con un campo opcional para cada columna Delta:

syntax = "proto2";
message AirQuality {
    optional string device_name = 1;
    optional int32 temp = 2;
    optional int64 humidity = 3;
}

2. Compilar el esquema a un módulo Python con el compilador protobuf:

pip install "grpcio-tools>=1.60.0,<2.0"
python -m grpc_tools.protoc --python_out=. --proto_path=. record.proto

Esto genera record_pb2.py.

3. Ingirir registros pasando el descriptor compilado a TableProperties (el predeterminado para protobuf). El SDK utiliza el descriptor para serializar cada registro:

import record_pb2

descriptor_bytes = record_pb2.AirQuality.DESCRIPTOR.file.serialized_pb
table_properties = TableProperties(TABLE_NAME, descriptor_bytes)
stream = sdk.create_stream(CLIENT_ID, CLIENT_SECRET, table_properties)

record = record_pb2.AirQuality(device_name="sensor-1", temp=22, humidity=55)
stream.ingest_record_offset(record)

El ejemplo anterior utiliza el SDK de Python. Las herramientas varían según el lenguaje de programación: algunos SDK incluyen una utilidad generate_proto que genera .proto a partir de tu tabla, mientras que otros (como Go y TypeScript) compilan un .proto existente. Para los pasos por lenguaje, consulta las notas protobuf en cada pestaña SDK de Escribe un cliente. Para fuentes de herramientas y ejemplos completos, véase el repositorio Zerobus SDK.

Flecha Apache

La ingestión de Apache Arrow envía datos de ArrowRecordBatch directamente por la misma conexión gRPC, en lugar de convertir primero cada fila a JSON o Protobuf. Es la mejor opción cuando tu aplicación ya produce datos de Arrow o cuando ingieres filas en lotes, especialmente para esquemas amplios, con mucha cantidad numérica o orientados a analítica donde la serialización fila por fila añade sobrecarga.

Arrow también es una buena opción para lotes muy grandes. A diferencia de los métodos JSON y protobuf batch, que son todo o nada y están limitados por el límite de tamaño por mensaje, la ruta de vuelo Arrow divide un lote grande en mensajes de transporte más pequeños que se envían y reconocen individualmente. Consulte los lotes de Arrow Flight son la excepción y Use Arrow Flight con Zerobus Ingest.

Abre un flujo Arrow con un pyarrow.Schema e ingiere RecordBatch datos:

stream = sdk.create_arrow_stream(TABLE_NAME, schema, CLIENT_ID, CLIENT_SECRET)

stream.ingest_batch(batch)

Para la guía completa de Arrow Flight, incluida la definición del esquema, el procesamiento por lotes y la compresión, consulte Usar Arrow Flight con Zerobus Ingest.

  • Last updated on