Description
Le formatProtobuf est le format Protocol Buffers.
Ce format nécessite un schéma de format externe, qui est mis en cache d’une requête à l’autre.
ClickHouse prend en charge :
- les syntaxes
proto2etproto3. - les champs
Repeated/optional/required.
_ (underscore) et . (point) sont considérés comme équivalents.
Si les types d’une colonne et d’un champ du message Protocol Buffers sont différents, la conversion nécessaire est appliquée.
Les messages imbriqués sont pris en charge. Par exemple, pour le champ z dans le type de message suivant :
x.y.z (ou x_y_z ou X.y_Z, etc.).
Les messages imbriqués conviennent en entrée ou en sortie d’une structure de données imbriquée.
Pour les champs mappés absents dans le format binaire :
- Les colonnes mappées ordinaires non nullables utilisent la valeur par défaut du champ du schéma protobuf (
proto2[default = …], sinon la valeur par défaut du type) lors de l’analyse, et non l’expressionDEFAULTde la table. - Les colonnes mappées
Nullable(...)prennent la valeurNULLlorsque le champ est absent (elles n’utilisent pas la valeur par défaut du champ ou du type protobuf). - Lorsque
input_format_protobuf_flatten_google_wrappersest activé pour les wrappersgoogle.protobuf.*Value:- un wrapper absent sur une colonne
Nullable(...)est traité comme un champ externe manquant et devientNULL; - un wrapper présent mais vide (
str {}) conserve la valeur par défaut du scalaire imbriqué (''/0) ; - une colonne non nullable mappée à un wrapper absent reçoit la valeur par défaut du scalaire imbriqué plutôt que
NULL.
- un wrapper absent sur une colonne
DEFAULT de la table (et les expressions par défaut) s’appliquent aux colonnes de table qui n’ont aucun champ correspondant dans le type de message lorsque input_format_defaults_for_omitted_fields est activé (par défaut). Si ce paramètre est défini sur 0, les colonnes non mappées conservent la valeur par défaut du type de données insérée lors de l’analyse, au lieu de l’expression DEFAULT de la table.
Exemple de valeur par défaut d’un champ de schéma proto2 (utilisée pour un champ mappé absent du message) :
input_format_protobuf_oneof_presence est défini, ClickHouse remplit la colonne indiquant quel champ du oneof a été trouvé.
input_format_protobuf_oneof_presence est désactivé par défaut
ClickHouse lit et écrit des messages protobuf au format length-delimited.
Cela signifie qu’avant chaque message, sa longueur doit être encodée sous la forme d’un entier de longueur variable (varint).
Exemple d’utilisation
Lecture et écriture de données
Les fichiers utilisés dans cet exemple sont disponibles dans le repository examples
protobuf_message.bin dans une table ClickHouse. Nous les écrirons ensuite
dans un fichier nommé protobuf_message_from_clickhouse.bin au format Protobuf.
Étant donné le fichier schemafile.proto :
Génération du fichier binaire
Génération du fichier binaire
Si vous savez déjà comment sérialiser et désérialiser des données au format Créez maintenant un nouveau fichier Python nommé Exécutez maintenant le script en ligne de commande. Il est recommandé de l’exécuter depuis un
environnement virtuel Python, par exemple avec Vous devrez installer la bibliothèque Python suivante :Exécutez le script pour générer le fichier binaire :
Protobuf, vous pouvez ignorer cette étape.Nous utiliserons Python pour sérialiser des données dans protobuf_message.bin et les lire dans ClickHouse.
Si vous souhaitez utiliser un autre langage, voir aussi : “How to read/write length-delimited Protobuf messages in popular languages”.Exécutez la commande suivante pour générer un fichier Python nommé schemafile_pb2.py dans
le même répertoire que schemafile.proto. Ce fichier contient les classes Python
qui représentent votre message Protobuf UserData :generate_protobuf_data.py, dans le même
répertoire que schemafile_pb2.py. Collez-y le code suivant :uv :Protobuf :
protobuf_message_from_clickhouse.bin.
Lecture et écriture de données avec ClickHouse Cloud
Avec ClickHouse Cloud, vous ne pouvez pas importer de fichier de schéma Protobuf. Vous pouvez toutefois utiliser le paramètreformat_schema_source
pour spécifier le schéma dans la requête. Dans cet exemple, nous vous montrons comment lire des données sérialisées depuis votre machine locale
et les insérer dans une table dans ClickHouse Cloud.
Comme dans l’exemple précédent, créez la table d’après le schéma Protobuf dans ClickHouse Cloud :
format_schema_source définit la source du paramètre format_schema
Valeurs possibles :
- ‘file’ (par défaut) : non pris en charge dans Cloud
- ‘string’ :
format_schemacorrespond au contenu littéral du schéma. - ‘query’ :
format_schemaest une requête permettant de récupérer le schéma.
format_schema_source='string'
Pour insérer les données dans ClickHouse Cloud en spécifiant le schéma sous forme de chaîne, exécutez :
format_schema_source='query'
Vous pouvez également stocker votre schéma Protobuf dans une table.
Créez dans ClickHouse Cloud une table dans laquelle insérer des données :
clickhouse client analyse les données d’entrée côté client, où la requête de schéma échoue.
L’option --url-query de curl (curl 7.87 et versions ultérieures) encode chaque paramètre au format URL ; la requête et la requête de schéma peuvent donc être écrites telles quelles :
Utilisation d’un schéma autogénéré
Si vous n’avez pas de schéma Protobuf externe pour vos données, vous pouvez tout de même écrire/lire des données au format Protobuf en utilisant un schéma autogénéré. Pour cela, utilisez le paramètreformat_protobuf_use_autogenerated_schema.
Par exemple :
structureToProtobufSchema. Il utilisera ensuite ce schéma pour sérialiser les données au format Protobuf.
Vous pouvez également lire un fichier Protobuf avec le schéma autogénéré. Dans ce cas, il est nécessaire que le fichier soit créé à partir du même schéma :
format_protobuf_use_autogenerated_schema est activé par défaut et s’applique si format_schema n’est pas défini.
Vous pouvez également enregistrer le schéma autogénéré dans le fichier lors des opérations d’entrée/sortie à l’aide du paramètre output_format_schema. Par exemple :
path/to/schema/schema.capnp.
Vider le cache Protobuf
Pour recharger le schéma Protobuf chargé à partir deformat_schema_path, utilisez l’instruction SYSTEM DROP ... FORMAT CACHE.