Types de messages
Lorsque vous effectuez une ingestion avec les SDK Zerobus Ingest via gRPC, vous choisissez la manière dont les enregistrements sont encodés sur un stream donné. Zerobus Ingest prend en charge trois formats de message (JSON, Protocol Buffers (protobuf) et Apache Arrow), ce qui vous permet de trouver le meilleur équilibre entre simplicité, sécurité des types et throughput pour votre workload. Chaque format est validé par rapport au schéma de votre table Delta avant que les données ne soient rendues durables. Consultez la gestion de schémas.
Quel format devez-vous utiliser ?
Format | Idéal pour | Notes |
|---|---|---|
JSON | Getting start et producteurs simples. | L'option la plus simple, sans définition de schéma à compiler. Pratique, mais plus lent que les formats binaires pour les charges de travail à haut volume. |
Protocol Buffers | Production, orientés ligne et à haut volume Stream. | Encodage binaire compact et sécurisé par le typage. Recommandé pour la plupart des charges de travail de production. Nécessite un schéma compilé. |
Apache Arrow | Charges de travail orientées colonnes ou par lots. | Envoie directement des batchs d'enregistrements Apache Arrow, évitant ainsi la sérialisation ligne par ligne. Idéal lorsque vos données sont déjà en colonnes ou que vous effectuez une ingestion par batch. En bêta. Consultez Utiliser Arrow Flight avec Zerobus Ingest. |
Les extraits ci-dessous montrent la forme de chaque format dans le SDK Python. Ils supposent que vous avez déjà créé le client SDK et que vous connaissez votre table cible. Pour la configuration complète (Endpoint, table, Service Principal) et des exemples dans chaque langue, voir Use Zerobus Ingest.
JSON
Le JSON est le moyen le plus simple de start : vous envoyez des enregistrements sous forme d'objets JSON sans définition de schéma à compiler. C'est idéal pour démarrer, prototyper et pour les producteurs où la commodité compte plus que le throughput brut. Pour les charges de travail de production à haut volume, un format binaire (protobuf ou Arrow) est plus efficace.
Créez un stream pour les enregistrements JSON en transmettant un nom de table à TableProperties sans descripteur :
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})
Pour le guide complet sur le JSON, consultez Écrire un client.
Protocol Buffers
Protobuf fournit un encodage binaire compact et sécurisé en termes de types, et constitue le format recommandé pour la plupart des charges de travail de production orientées lignes. Vous définissez un schéma protobuf adapté à votre table Delta cible (voir schéma Protobuf), vous le compilez, et le SDK ingère les enregistrements un par un via gRPC.
L'utilisation de protobuf se fait en trois étapes : générer un schéma .proto correspondant à votre table, le compiler en un module de langage, puis ingérer les enregistrements en transmettant le descripteur à TableProperties. L'exemple suivant utilise le SDK Python.
1. Générez un schéma .proto à partir de votre table. Le SDK Python inclut un outil generate_proto qui lit votre table Delta et écrit un schéma correspondant :
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"
Le schéma généré utilise la syntaxe proto2, avec un champ facultatif pour chaque colonne Delta :
syntax = "proto2";
message AirQuality {
optional string device_name = 1;
optional int32 temp = 2;
optional int64 humidity = 3;
}
2. Compilez le schéma en un module Python avec le compilateur protobuf :
pip install "grpcio-tools>=1.60.0,<2.0"
python -m grpc_tools.protoc --python_out=. --proto_path=. record.proto
Ceci génère record_pb2.py.
3. Ingestez les enregistrements en transmettant le descripteur compilé à TableProperties (the default pour protobuf). Le SDK utilise le descripteur pour sérialiser chaque enregistrement :
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'exemple ci-dessus utilise le SDK Python. Les outils varient selon le langage : certains SDK fournissent un utilitaire generate_proto qui génère un .proto à partir de votre table, tandis que d'autres (comme Go et TypeScript) compilent un .proto existant. Pour les étapes par langage, consultez les notes protobuf dans chaque onglet SDK de Write a client. Pour les sources des outils et des exemples complets, consultez le repository du SDK Zerobus.
Apache Arrow
Bêta
L'ingestion Apache Arrow est en Bêta.
L'ingestion Apache Arrow envoie les données Arrow RecordBatch directement via la même connexion gRPC, au lieu de convertir chaque ligne en JSON ou protobuf au préalable. C'est le meilleur choix lorsque votre application produit déjà des données Arrow ou lorsque vous ingérez des lignes par batch, en particulier pour les schémas larges, à forte composante numérique ou orientés analytique, où la sérialisation ligne par ligne ajoute une surcharge.
Arrow est également bien adapté aux très grands batchs. Contrairement aux méthodes par batch JSON et protobuf, qui fonctionnent sur le principe du tout ou rien et sont limitées par la taille maximale par message, le chemin Arrow Flight divise un batch volumineux en messages de transport plus petits qui sont envoyés et accusés de réception individuellement. Voir Les batchs Arrow Flight sont l'exception et Utiliser Arrow Flight avec Zerobus Ingest.
Ouvrez un Stream Arrow avec un pyarrow.Schema et ingérez des données RecordBatch :
stream = sdk.create_arrow_stream(TABLE_NAME, schema, CLIENT_ID, CLIENT_SECRET)
stream.ingest_batch(batch)
Pour le guide complet sur Arrow Flight, incluant la définition de schéma, le batching et la compression, consultez Utiliser Arrow Flight avec Zerobus Ingest.
Connexes
- Protocoles API: les protocoles API sur lesquels ces formats transitent.
- Gestion des schémas: comment les enregistrements sont validés par rapport à votre table.
- Types de données pris en charge: types de données Delta et Protobuf pris en charge.