Tipos de mensagem

Ao ingerir com os SDKs Zerobus Ingest através de gRPC, escolhe como os registos são codificados num determinado fluxo. O Zerobus Ingest suporta três formatos de mensagem (JSON, Protocol Buffers (protobuf) e Apache Arrow), por isso pode trocar simplicidade, segurança de tipos e rendimento para a sua carga de trabalho. Cada formato é validado contra o esquema da tabela Delta antes de os dados se tornarem duráveis. Ver Gestão de esquemas.

Os mesmos 1.000 registos em três formatos de mensagem: protobuf como uma codificação compacta e tipada por linha, Apache Arrow como um lote colunar cujos metadados e buffers são distribuídos pelo lote, e JSON como texto legível com nomes de campos repetidos

Que formato deves usar?

Format Melhor para Observações
JSON Introdução e produtores básicos. 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 Produção, fluxos baseados em linhas, de alto volume. Codificação binária compacta com segurança de tipos. Recomendado para a maioria das cargas de trabalho em produção. Requer um esquema compilado.
Apache Arrow Cargas de trabalho colunares ou orientadas por lotes. Envia lotes de registos Apache Arrow diretamente, evitando serialização linha a linha. É melhor quando os teus dados já são colunares ou ingeres em lotes. Veja Usar Arrow Flight com Zerobus Ingest.

Os excertos abaixo mostram a forma de cada formato no SDK Python. Eles assumem que já criaste o cliente SDK e conheces a tua tabela de destino. Para obter a configuração completa (endpoint, tabela, principal de serviço) e exemplos em todas as linguagens, consulte Use Zerobus Ingest.

JSON

JSON é a forma mais simples de começar: envias registos como objetos JSON sem definição de esquema para compilar. É ideal para começar rapidamente a trabalhar, criar protótipos e para produtores para quem a conveniência é mais importante do que o desempenho bruto. Para cargas de trabalho de produção de grande volume, um formato binário (protobuf ou Arrow) é mais eficiente.

Crie um fluxo para registos 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 guia completo em JSON, consulte Escrever um cliente.

Buffers de protocolo

O Protobuf fornece uma codificação binária compacta e segura para tipos, sendo o formato recomendado para a maioria das cargas de trabalho de produção orientadas a linhas. Defines um esquema protobuf que se ajusta à tua tabela Delta de destino (ver esquema Protobuf), compilas-no, e o SDK ingere registos registo a registo sobre gRPC.

Usar protobuf tem três passos: gerar um .proto esquema que corresponda à sua tabela, compilá-lo para um módulo de linguagem e depois ingerir registos passando o descritor para TableProperties. O exemplo seguinte utiliza o SDK Python.

1. Gerar um .proto esquema a partir da sua tabela. O SDK Python inclui uma generate_proto ferramenta que lê a sua tabela Delta e escreve 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 utiliza proto2 sintaxe, 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. Compilar 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

Isto gera record_pb2.py.

3. Ingerir registos passando o descritor compilado para TableProperties (o padrão para protobuf). O SDK usa o descritor para serializar cada registo:

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 Python. As ferramentas variam consoante a linguagem: alguns SDKs incluem um utilitário generate_proto que gera uma .proto a partir da sua tabela, enquanto outros (como Go e TypeScript) compilam um .proto existente. Para os passos para cada linguagem, consulte as notas sobre protobuf em cada separador do SDK de Write a client. Para fontes de ferramentas e exemplos completos, consulte o repositório Zerobus SDK.

Apache Arrow

A ingestão com Apache Arrow envia dados ArrowRecordBatch diretamente através da mesma ligação gRPC, em vez de converter primeiro cada linha em JSON ou protobuf. É a melhor escolha quando a sua aplicação já produz dados Arrow ou quando ingere linhas em lotes, especialmente para esquemas amplos, com muitos números ou orientados para análise, 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 JSON e protobuf batch, que são tudo ou nada e limitados pelo limite de tamanho por mensagem, o Arrow Flight Path divide um grande lote em mensagens de transporte mais pequenas que são enviadas e reconhecidas individualmente. Veja que os lotes Arrow Flight são a exceção e use o Arrow Flight com Zerobus Ingest.

Abra um fluxo Arrow com um pyarrow.Schema e importe dados RecordBatch:

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

stream.ingest_batch(batch)

Para o guia completo do Arrow Flight, incluindo a definição do esquema, o processamento em lotes e a compressão, consulte Utilizar o Arrow Flight com o Zerobus Ingest.

  • Last updated on