Berichttypen

Wanneer je invoert met de Zerobus Ingest SDK's in plaats van gRPC, kies je hoe records op een bepaalde stream worden gecodeerd. Zerobus Ingest ondersteunt drie berichtformaten (JSON, Protocol Buffers (protobuf) en Apache Arrow), zodat je eenvoud, typeveiligheid en doorvoer kunt afwegen voor je werklast. Elk formaat wordt gevalideerd aan de hand van je Delta-tabel voordat de data duurzaam wordt gemaakt. Zie Schemabeheer.

Dezelfde 1.000 records in drie berichtformaten: protobuf als compacte, getypte rijcodering, Apache Arrow als één kolombatch waarvan metadata en buffers over de batch worden geamortiseerd, en JSON als leesbare tekst met herhaalde veldnamen

Welk formaat moet je gebruiken?

Format Geschikt voor Opmerkingen
JSON Beginnen en eenvoudige producenten. De eenvoudigste optie, zonder schema-definitie om te compileren. Handig, maar langzamer dan de binaire formaten voor workloads met een groot volume.
Protocolbuffers Productie-, rijgeoriënteerde hoogvolumegegevensstromen. Typeveilige, compacte binaire codering. Aanbevolen voor de meeste productieworkloads. Vereist een gecompileerd schema.
Apache Arrow Kolom- of batchgeoriënteerde werklasten. Stuurt Apache Arrow-recordbatches direct, waardoor rij-voor-rij serialisatie wordt vermeden. Het beste is wanneer je data al columnar is of je het in batches invoert. Zie Arrow Flight gebruiken met Zerobus Ingest.

De onderstaande fragmenten tonen de vorm van elk formaat in de Python SDK. Ze gaan ervan uit dat je de SDK-client al hebt gemaakt en je doeltabel kent. Voor de volledige opzet (endpoint, table, service principal) en voorbeelden in elke taal, zie Use Zerobus Ingest.

JSON

JSON is de eenvoudigste manier om te beginnen: je stuurt records als JSON-objecten zonder schema-definitie om te compileren. Het is ideaal om snel aan de slag te gaan, te prototypen en voor productieworkloads waarbij gebruiksgemak belangrijker is dan ruwe doorvoercapaciteit. Voor productiewerklasten met een groot volume is een binair formaat (protobuf of Arrow) efficiënter.

Maak een stream aan voor JSON-records door een tabelnaam zonder descriptor door te TableProperties geven:

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

Voor de volledige JSON-walkthrough, zie Write a client.

Protocolbuffers

Protobuf biedt een typeveilige, compacte binaire codering en is het aanbevolen formaat voor de meeste productie-, rijgerichte workloads. Je definieert een protobuf-schema dat past bij je doel-Delta-tabel (zie Protobuf-schema), compileert het, en de SDK verwerkt records record-voor-record via gRPC.

Het gebruik van protobuf vereist drie stappen: een .proto schema genereren dat overeenkomt met je tabel, het compileren naar een taalmodule, en vervolgens records invoeren door de descriptor aan door te TablePropertiesgeven. Het volgende voorbeeld gebruikt de Python SDK.

1. Genereer een .proto schema uit je tabel. De Python SDK bevat een generate_proto tool die je Delta-tabel leest en een bijpassend schema schrijft:

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"

Het gegenereerde schema gebruikt proto2 syntaxis, met een optioneel veld voor elke Delta-kolom:

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

2. Compileer het schema naar een Python-module met de protobuf-compiler:

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

Dit genereert record_pb2.py.

3. Invoer records door de gecompileerde descriptor aan TableProperties te geven (de standaard voor protobuf). De SDK gebruikt de descriptor om elk record te serialiseren:

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)

Het bovenstaande voorbeeld gebruikt de Python SDK. De tooling verschilt per taal: sommige SDK's leveren een generate_proto utility die een .proto genereert uit je tabel, terwijl anderen (zoals Go en TypeScript) een bestaande .protocompileren. Voor de stappen per taal, zie de protobuf-notities in elk SDK-tabblad van Write a client. Voor hulpbronnen en volledige voorbeelden, zie de Zerobus SDK-repository.

Apache Arrow

De invoering van Apache Arrow stuurt Arrow-gegevensRecordBatch rechtstreeks via dezelfde gRPC-verbinding, in plaats van eerst elke rij om te zetten naar JSON of Protobuf. Het is de beste keuze wanneer je applicatie al Arrow-data produceert of wanneer je rijen in batches invoert, vooral bij brede, numeriek georiënteerde of analytics-georiënteerde schema's waarbij rij-voor-rij serialisatie extra overhead veroorzaakt.

Arrow is ook een goede keuze voor zeer grote batches. In tegenstelling tot de JSON- en protobuf-batchmethoden, die alles-of-niets zijn en begrensd door de limiet per berichtgrootte, splitst het Arrow Flight-pad een grote batch op in kleinere transportberichten die individueel worden verzonden en bevestigd. Zie Arrow Flight-batches zijn de uitzondering en gebruik Arrow Flight met Zerobus Ingest.

Open een Arrow-stream met een pyarrow.Schema en neem RecordBatch-gegevens op:

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

stream.ingest_batch(batch)

Voor de volledige Arrow Flight-walkthrough, inclusief schema-definitie, batching en compressie, zie Use Arrow Flight with Zerobus Ingest.

  • Last updated on