Tipos de Mensagem

Quando você faz a ingestão com os SDKs de ingestão do Zerobus via gRPC, você escolhe como os registros são codificados em um determinado fluxo. O Zerobus Ingest suporta três formatos de mensagem (JSON, Protocol Buffers (protobuf) e Apache Arrow), para que você possa equilibrar simplicidade, segurança de tipos e taxa de transferência de acordo com sua carga de trabalho. Cada formato é validado contra o esquema da tabela Delta antes que os dados se tornem duráveis. Veja Gerenciamento de esquemas.

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

Qual formato você deve usar?

Formato Melhor para Notes
JSON Introdução e produtores simples. A opção mais simples, sem definição de esquema para compilar. Conveniente, mas mais lento 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 com segurança de tipos. Recomendado para a maioria das cargas de trabalho em produção. Requer um esquema compilado.
Flecha Apache Cargas de trabalho colunares ou orientadas a lotes. Envia lotes de registros do Apache Arrow diretamente, evitando a serialização linha por linha. Ideal quando seus dados já são colunares ou a ingestão é feita em lotes. Consulte Usar Arrow Flight com Zerobus Ingest.

Os trechos abaixo mostram o formato de cada formato no SDK Python. Eles assumem que você já criou o cliente SDK e conhece sua tabela de alvo. Para a configuração completa (ponto de extremidade, tabela, entidade de serviço) e exemplos em todas as linguagens, consulte Usar o Zerobus Ingest.

JSON

JSON é a forma mais simples de começar: você envia registros como objetos JSON sem definição de esquema para compilar. É ideal para colocar em funcionamento, prototipar e para produtores para quem a conveniência importa mais do que o desempenho bruto. Para cargas de trabalho de produção de alto volume, um formato binário (protobuf ou Arrow) é mais eficiente.

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

Protocol Buffers

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. Você define um esquema protobuf que se encaixa na sua tabela Delta de destino (veja esquema Protobuf), compila e o SDK ingere registros registro por registro via gRPC.

Usar protobuf segue três etapas: gerar um .proto esquema que corresponda à sua tabela, compilá-lo em um módulo de linguagem e então ingerir registros passando o descritor para TableProperties. O exemplo a seguir usa o SDK Python.

1. Gerar um .proto esquema a partir da sua tabela. O SDK Python inclui uma generate_proto ferramenta que lê 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 usa 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

Isso gera record_pb2.py.

3. Ingerir registros passando o descritor compilado para TableProperties (o padrão 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 Python. O ferramental varia conforme a linguagem: alguns SDKs incluem o utilitário generate_proto, que gera um(a) .proto com base na sua tabela, enquanto outros (como Go e TypeScript) compilam um .proto existente. Para as etapas específicas de cada idioma, consulte as notas sobre protobuf em cada aba do SDK de Write a client. Para fontes de ferramentas e exemplos completos, veja o repositório Zerobus SDK.

Flecha Apache

A ingestão com Apache Arrow envia dados de ArrowRecordBatch diretamente pela mesma conexão gRPC, em vez de converter primeiro cada linha para JSON ou protobuf. É a melhor escolha quando sua aplicação já produz dados Arrow ou quando você ingere linhas em lotes, especialmente para esquemas largos, com predominância de dados numéricos ou voltados para análises, em que a serialização linha a linha gera sobrecarga.

O Arrow também é uma boa opção para lotes muito grandes. Diferentemente dos métodos de lote JSON e protobuf, que funcionam no esquema tudo ou nada e estão sujeitos ao limite de tamanho por mensagem, o caminho do Arrow Flight divide um lote grande em mensagens de transporte menores, enviadas e confirmadas individualmente. Consulte Os lotes do Arrow Flight são uma exceção e Usar o Arrow Flight com o Zerobus Ingest.

Abra uma transmissão do Arrow com pyarrow.Schema e faça a ingestão de 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 lotes e compressão, veja Use o Arrow Flight com o Zerobus Ingest.

  • Last updated on