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

CapnProto

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

描述​

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

另请参见 格式模式。

数据类型匹配​

下表显示了支持的数据类型以及它们如何在 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'"

使用自动生成的模式​

如果您没有外部 CapnProto 模式用于您的数据，您仍然可以使用自动生成的模式在 CapnProto 格式中输出/输入数据。

例如：

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

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

您还可以读取具有自动生成模式的 CapnProto 文件（在这种情况下，文件必须使用相同的模式创建）：

$ 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 将自动生成的模式保存到文件中。

例如：

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 中。