CapnProto

Documentation sur CapnProto

Entrée	Sortie	Alias
✔	✔

​

Description

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.

​

Correspondance des types de données

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.

Type de données CapnProto (INSERT)	Type de données ClickHouse	Type de données CapnProto (SELECT)
UINT8, BOOL	UInt8	UINT8
INT8	Int8	INT8
UINT16	UInt16, Date	UINT16
INT16	Int16	INT16
UINT32	UInt32, DateTime	UINT32
INT32	Int32, Decimal32	INT32
UINT64	UInt64	UINT64
INT64	Int64, DateTime64, Decimal64	INT64
FLOAT32	Float32	FLOAT32
FLOAT64	Float64	FLOAT64
TEXT, DATA	String, FixedString	TEXT, DATA
union(T, Void), union(Void, T)	Nullable(T)	union(T, Void), union(Void, T)
ENUM	Enum(8/16)	ENUM
LIST	Array	LIST
STRUCT	Tuple	STRUCT
UINT32	IPv4	UINT32
DATA	IPv6	DATA
DATA	Int128/UInt128/Int256/UInt256	DATA
DATA	Decimal128/Decimal256	DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))	Map	STRUCT(entries LIST(STRUCT(key Key, value Value)))

• 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.

​

Exemple d’utilisation

​

Insertion et sélection de données

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'"

​

Utilisation d’un schéma généré automatiquement

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"

​

Paramètres de format

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.