Tipi di messaggio

Quando ingeri con gli SDK di Zerobus Ingest tramite gRPC, scegli come vengono codificati i record su un dato stream. Zerobus Ingest supporta tre formati di messaggi (JSON, Protocol Buffers (protobuf) e Apache Arrow), così da poter bilanciare semplicità, sicurezza dei tipi e throughput in base al tuo carico di lavoro. Ogni formato viene validato rispetto allo schema della tabella Delta prima che i dati diventino resi durevoli. Vedi Gestione degli schemi.

Gli stessi 1.000 record in tre formati di messaggio: protobuf come codifica compatta e tipizzata per righe, Apache Arrow come un batch in formato colonnare i cui metadati e buffer sono ripartiti sull'intero batch, e JSON come testo leggibile con nomi di campi ripetuti

Quale formato dovresti usare?

Format Ideale per Note
JSON Iniziare e semplici produttori. L'opzione più semplice, senza definizione di schema da compilare. Comodi, ma più lenti dei formati binari per carichi di lavoro ad alto volume.
Buffer di protocollo Produzione, file orientate a righe, flussi ad alto volume. Codifica binaria compatta e sicura per i tipi. Consigliato per la maggior parte dei carichi di lavoro in produzione. Richiede uno schema compilato.
Apache Arrow Carichi di lavoro colonnari o orientati ai batch. Invia direttamente i batch di record Apache Arrow, evitando la serializzazione riga per riga. Ideale quando i dati sono già in formato colonnare o vengono acquisiti in modalità batch. In Beta. Vedi Usare Arrow Flight con Zerobus Ingest.

Gli estratti qui sotto mostrano la forma di ciascun formato nell'SDK Python. Presuppongono che tu abbia già creato il client SDK e conosca la tabella di destinazione. Per la configurazione completa (endpoint, tabella, principale di servizio) e esempi in ogni linguaggio, vedi Usa Zerobus Ingest.

JSON

JSON è il modo più semplice per iniziare: invii i record come oggetti JSON senza definizione di schema da compilare. È ideale per avviare e funzionare, prototipare e produrre dove la comodità conta più della capacità bruta. Per carichi di lavoro di produzione ad alto volume, un formato binario (protobuf o Arrow) è più efficiente.

Crea un flusso per i record JSON passando il nome di una tabella a TableProperties senza descrittore:

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})

Per una guida dettagliata completa su JSON, vedi Scrivere un client.

Buffer di protocollo

Protobuf fornisce una codifica binaria compatta con controllo dei tipi ed è il formato consigliato per la maggior parte dei workload di produzione basati su righe. Definisci uno schema protobuf compatibile con la tua tabella Delta di destinazione (vedi schema Protobuf), lo compili e l'SDK acquisisce i record uno alla volta tramite gRPC.

L'uso di protobuf richiede tre passaggi: generare uno .proto schema che corrisponda alla tua tabella, compilarlo in un modulo linguistico, poi ingerire i record passando il descrittore a TableProperties. Il seguente esempio utilizza l'SDK Python.

1. Genera uno .proto schema dalla tua tabella. L'SDK Python include uno generate_proto strumento che legge la tua tabella Delta e scrive uno schema corrispondente:

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"

Lo schema generato utilizza proto2 la sintassi, con un campo opzionale per ogni colonna Delta:

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

2. Compilare lo schema in un modulo Python con il compilatore protobuf:

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

In questo modo viene generato record_pb2.py.

3. Ingerire i record passando il descrittore compilato a TableProperties (il valore predefinito per protobuf). L'SDK usa il descrittore per serializzare ogni record:

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)

L'esempio sopra utilizza l'SDK Python. Gli strumenti variano a seconda del linguaggio: alcuni SDK forniscono un'utilità generate_proto che genera a .proto dalla tua tabella, mentre altri (come Go e TypeScript) compilano un .proto. Per i passaggi per linguaggio, consulta le note protobuf in ogni scheda SDK di Scrivi un client. Per le fonti degli strumenti ed esempi completi, vedi il repository Zerobus SDK.

Apache Arrow

Importante

L'acquisizione di Apache Arrow è in Beta.

L'ingestione di Apache Arrow invia i dati ArrowRecordBatch direttamente sulla stessa connessione gRPC, invece di convertire prima ogni riga in JSON o protobuf. È la scelta migliore quando la tua applicazione produce già dati Arrow o quando acquisisci righe in batch, soprattutto per schemi estesi, a prevalenza numerica o orientati all'analisi, in cui la serializzazione riga per riga aggiunge overhead.

Arrow è anche una buona scelta per lotti molto grandi. A differenza dei metodi batch JSON e protobuf, che sono tutto o niente e limitati dal limite di dimensione per messaggio, il percorso Arrow Flight divide un grande batch in messaggi di trasporto più piccoli che vengono inviati e riconosciuti individualmente. Consulta I batch Arrow Flight fanno eccezione e Usa Arrow Flight con Zerobus Ingest.

Apri un flusso Arrow con un pyarrow.Schema e acquisisci i dati RecordBatch:

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

stream.ingest_batch(batch)

Per la guida completa di Arrow Flight, inclusa la definizione dello schema, l'elaborazione in batch e la compressione, consulta Usa Arrow Flight con Zerobus Ingest.

  • Last updated on