CapnProto

CapnProto 的文档

输入	输出	别名
✔	✔

​

说明

CapnProto 格式是一种二进制消息格式，类似于 Protocol Buffers 和 Thrift，但不同于 JSON 或 MessagePack。 CapnProto 消息具有严格的类型约束，且不是自描述的，这意味着它们需要外部 schema 描述。schema 会在运行时应用，并按每个查询缓存。

另请参见 Format Schema。

​

数据类型匹配

下表展示了支持的数据类型，以及它们在 INSERT 和 SELECT 查询中与 ClickHouse 数据类型 的对应关系。

CapnProto 数据类型 (INSERT)	ClickHouse 数据类型	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)))

• 整数类型在输入和输出时可以相互转换。
• 如需在 CapnProto 格式中使用 Enum，请使用 format_capn_proto_enum_comparising_mode 设置。
• 数组可以嵌套，其参数也可以是 Nullable 类型。Tuple 和 Map 类型同样也可以嵌套。

​

使用示例

​

插入和查询数据

你可以使用以下命令，将文件中的 CapnProto 数据插入到 ClickHouse 表中：

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

其中，schema.capnp 的内容如下：

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

您可以使用以下命令从 ClickHouse 表中查询数据，并将其以 CapnProto 格式保存到文件中：

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

​

使用自动生成的 schema

如果你的数据没有外部 CapnProto schema，仍然可以借助自动生成的 schema，以 CapnProto 格式 输出或输入数据。

例如：

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

在这种情况下，ClickHouse 将使用函数 structureToCapnProtoSchema 根据表结构自动生成 CapnProto schema，并使用该 schema 以 CapnProto 格式序列化数据。

你也可以使用自动生成的 schema 读取 CapnProto 文件 (在这种情况下，文件必须使用相同的 schema 创建) ：

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

​

格式设置

设置 format_capn_proto_use_autogenerated_schema 默认已启用，并且在未设置 format_schema 时生效。

你也可以在输入/输出时，使用设置 output_format_schema 将自动生成的 schema 保存到文件中。

例如：

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

在这种情况下，自动生成的 CapnProto schema 将保存到文件 path/to/schema/schema.capnp 中。