跳到主要内容
跳到主要内容

CapnProto

Not supported in ClickHouse Cloud
输入输出别名
✔✔

描述​

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

另请参阅 Format Schema。

数据类型匹配​

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

CapnProto 数据类型（INSERT）ClickHouse 数据类型CapnProto 数据类型（SELECT）
UINT8, BOOLUInt8UINT8
INT8Int8INT8
UINT16UInt16, DateUINT16
INT16Int16INT16
UINT32UInt32, DateTimeUINT32
INT32Int32, Decimal32INT32
UINT64UInt64UINT64
INT64Int64, DateTime64, Decimal64INT64
FLOAT32Float32FLOAT32
FLOAT64Float64FLOAT64
TEXT, DATAString, FixedStringTEXT, DATA
union(T, Void), union(Void, T)Nullable(T)union(T, Void), union(Void, T)
ENUMEnum(8/16)ENUM
LISTArrayLIST
STRUCTTupleSTRUCT
UINT32IPv4UINT32
DATAIPv6DATA
DATAInt128/UInt128/Int256/UInt256DATA
DATADecimal128/Decimal256DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))MapSTRUCT(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 模式将会保存在文件 path/to/schema/schema.capnp 中。