CapnProto

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

另请参见 Format Schema。

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

• 整数类型在输入和输出时可以相互转换。
• 如需在 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'"

如果你的数据没有外部 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 中。