CapnProto

Le format CapnProto est un format de messages binaires semblable au format Protocol Buffers et à Thrift, mais contrairement à JSON ou à MessagePack. Les messages CapnProto sont strictement typés et ne sont pas auto-descriptifs, ce qui signifie qu'ils nécessitent une description de schéma externe. Le schéma est appliqué à la volée et mis en cache pour chaque requête.

Voir aussi Schéma de format.

Le tableau ci-dessous présente les types de données pris en charge et leur correspondance avec les types de données ClickHouse dans les requêtes INSERT et SELECT.

• Les types entiers peuvent être convertis les uns dans les autres lors des opérations d'entrée/sortie.
• Pour utiliser Enum au format CapnProto, utilisez le paramètre format_capn_proto_enum_comparising_mode.
• Les Array peuvent être imbriqués et accepter une valeur de type Nullable comme argument. Les types Tuple et Map peuvent également être imbriqués.

Vous pouvez insérer des données CapnProto à partir d’un fichier dans une table ClickHouse à l’aide de la commande suivante :

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

où le schema.capnp se présente ainsi :

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

Vous pouvez sélectionner des données d’une table ClickHouse et les enregistrer dans un fichier au format CapnProto à l’aide de la commande suivante :

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

Si vous ne disposez pas d’un schéma CapnProto externe pour vos données, vous pouvez tout de même lire/écrire des données au format CapnProto à l’aide d’un schéma généré automatiquement.

Par exemple :

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS format_capn_proto_use_autogenerated_schema=1

Dans ce cas, ClickHouse générera automatiquement un schéma CapnProto à partir de la structure de la table à l’aide de la fonction structureToCapnProtoSchema et utilisera ce schéma pour sérialiser les données au format CapnProto.

Vous pouvez également lire un fichier CapnProto avec un schéma généré automatiquement (dans ce cas, le fichier doit être créé à l’aide du même schéma) :

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_capn_proto_use_autogenerated_schema=1 FORMAT CapnProto"

Le paramètre format_capn_proto_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 généré automatiquement dans un fichier lors des opérations d'entrée/sortie à l'aide du paramètre output_format_schema.

Par exemple :

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS 
    format_capn_proto_use_autogenerated_schema=1,
    output_format_schema='path/to/schema/schema.capnp'

Dans ce cas, le schéma CapnProto généré automatiquement sera enregistré dans le fichier path/to/schema/schema.capnp.