CapnProto

ClickHouse Cloud 中不支持

输入	输出	别名
✔	✔

描述

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

另请参阅 格式 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 中。