Protobuf

ClickHouse Cloud 中不支持

输入	输出	别名
✔	✔

描述

Protobuf 格式是 Protocol Buffers 格式。

此格式需要外部格式 schema，该 schema 在查询之间缓存。

ClickHouse 支持

使用示例

SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.table SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

其中文件 schemafile.proto 看起来像这样

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

为了找到表列和 Protocol Buffers 消息类型的字段之间的对应关系，ClickHouse 会比较它们的名称。此比较不区分大小写，字符 _（下划线）和 .（点）被视为相等。如果 Protocol Buffers 消息的列和字段的类型不同，则会应用必要的转换。

支持嵌套消息。例如，对于以下消息类型中的字段 z

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouse 尝试查找名为 x.y.z（或 x_y_z 或 X.y_Z 等）的列。

嵌套消息适用于嵌套数据结构的输入或输出。

在 protobuf schema 中定义的默认值（如下所示）不适用，而是使用表默认值代替它们

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

ClickHouse 以 length-delimited 格式输入和输出 protobuf 消息。这意味着在每条消息之前，其长度应以可变宽度整数 (varint) 形式写入。

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

例如

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

在这种情况下，ClickHouse 将使用函数 structureToProtobufSchema 根据表结构自动生成 Protobuf schema。然后，它将使用此 schema 以 Protobuf 格式序列化数据。

您还可以使用自动生成的 schema 读取 Protobuf 文件。在这种情况下，文件必须使用相同的 schema 创建

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

您还可以在输入/输出期间使用设置 output_format_schema 将自动生成的 schema 保存在文件中。例如

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

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

要重新加载从 format_schema_path 加载的 Protobuf schema，请使用 SYSTEM DROP ... FORMAT CACHE 语句。

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf