Tipos de mensagem
Ao ingerir dados com os SDKs do Zerobus Ingest via gRPC, você escolhe como os registros são codificados em uma determinada transmissão. O Zerobus Ingest oferece suporte a três formatos de mensagem (JSON, Protocol Buffers (protobuf) e Apache Arrow), para que você possa equilibrar simplicidade, segurança de tipo e throughput para sua carga de trabalho. Cada formato é validado em relação ao esquema da sua tabela Delta antes que os dados sejam tornados duráveis. Consulte Gerenciamento de esquemas.
Qual formato você deve usar?
Formato | Melhor para | Notas |
|---|---|---|
JSON | Introdução e produtores simples. | A opção mais simples, sem definição de esquema para compilar. Conveniente, mas mais lento do que os formatos binários para cargas de trabalho de alto volume. |
Buffers de protocolo | Transmissões de produção, orientadas a linhas e de alto volume. | Codificação binária compacta e type-safe. Recomendado para a maioria das cargas de trabalho de produção. Requer um esquema compilado. |
Apache Arrow | Cargas de trabalho colunares ou orientadas a lotes. | Envia lotes de registros do Apache Arrow diretamente, evitando a serialização linha a linha. Ideal quando seus dados já são colunares ou quando você realiza a ingestão em lotes. Em Beta. Consulte Usar o Arrow Flight com o Zerobus Ingest. |
Os snippets abaixo mostram o formato de cada estrutura no SDK do Python. Eles pressupõem que você já tenha criado o cliente do SDK e conheça sua tabela de destino. Para a configuração completa (endpoint, tabela, service principal) e exemplos em todos os idiomas, consulte Use Zerobus Ingest.
JSON
JSON é a maneira mais simples de começar: você envia registros como objetos JSON sem definição de esquema para compilar. É ideal para começar a operar, prototipar e para produtores onde a conveniência importa mais do que o throughput bruto. Para cargas de trabalho de produção de alto volume, um formato binário (protobuf ou Arrow) é mais eficiente.
Crie uma transmissão para registros JSON passando um nome de tabela para TableProperties sem descritor:
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 o passo a passo completo do JSON, consulte Escrever um cliente.
Buffers de protocolo
O Protobuf fornece uma codificação binária compacta e segura quanto ao tipo, sendo o formato recomendado para a maioria das cargas de trabalho de produção orientadas a linhas. Você define um esquema Protobuf que se ajusta à sua tabela Delta de destino (consulte Esquema Protobuf), compila-o e o SDK ingere registros, um por um, via gRPC.
Usar protobuf requer três passos: gerar um esquema .proto que corresponda à sua tabela, compilá-lo para um módulo de linguagem e, em seguida, ingerir registros passando o descritor para TableProperties. O exemplo a seguir usa o SDK do Python.
1. Gere um esquema .proto a partir da sua tabela. O SDK Python inclui uma ferramenta generate_proto que lê sua tabela Delta e grava um esquema correspondente:
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"
O esquema gerado usa a sintaxe proto2, com um campo opcional para cada coluna Delta:
syntax = "proto2";
message AirQuality {
optional string device_name = 1;
optional int32 temp = 2;
optional int64 humidity = 3;
}
2. Compile o esquema para um módulo Python com o compilador protobuf:
pip install "grpcio-tools>=1.60.0,<2.0"
python -m grpc_tools.protoc --python_out=. --proto_path=. record.proto
Isso gera record_pb2.py.
3. Ingerir registros passando o descritor compilado para TableProperties (o default para protobuf). O SDK usa o descritor 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)
O exemplo acima usa o SDK do Python. As ferramentas variam de acordo com a linguagem: alguns SDKs fornecem uma utilidade generate_proto que gera um .proto a partir da sua tabela, enquanto outros (como Go e TypeScript) compilam um .proto existente. Para os passos por linguagem, consulte as notas de protobuf em cada tab de SDK de Escrever um cliente. Para fontes de ferramentas e exemplos completos, consulte o repository do Zerobus SDK.
Apache Arrow
Beta
A ingestão do Apache Arrow está em Beta.
A ingestão do Apache Arrow envia dados Arrow RecordBatch diretamente pela mesma conexão gRPC, em vez de converter cada linha para JSON ou protobuf primeiro. É a melhor escolha quando sua aplicação já produz dados Arrow ou quando você ingere linhas em lotes, especialmente para esquemas amplos, com muitos dados numéricos ou orientados a análises, onde a serialização linha a linha adiciona sobrecarga.
O Arrow também é uma boa opção para lotes muito grandes. Ao contrário dos métodos de lote JSON e protobuf, que são tudo ou nada e limitados pelo tamanho máximo por mensagem, o caminho do Arrow Flight divide um lote grande em mensagens de transporte menores que são enviadas e confirmadas individualmente. Consulte Os lotes do Arrow Flight são a exceção e Usar o Arrow Flight com o Zerobus Ingest.
Abra uma transmissão Arrow com um pyarrow.Schema e ingira dados RecordBatch:
stream = sdk.create_arrow_stream(TABLE_NAME, schema, CLIENT_ID, CLIENT_SECRET)
stream.ingest_batch(batch)
Para o passo a passo completo do Arrow Flight, incluindo definição de esquema, processamento em lote e compressão, consulte Usar o Arrow Flight com o Zerobus Ingest.
Relacionado
- Protocolos de API: Os protocolos de API pelos quais esses formatos trafegam.
- Gerenciamento de esquema: Como os registros são validados em relação à sua tabela.
- Tipos de dados compatíveis: Tipos de dados Delta e Protobuf compatíveis.