Skip to main content

​
支持的数据源

​
隔离级别

Kafka 消费者隔离级别决定 ClickPipe 是否只读取和插入由 Kafka 事务提交的消息。启用 kafka_read_committed 设置可使用 read_committed，并跳过已中止的 Kafka 事务中的消息。禁用该设置则使用 read_uncommitted，读取所有消息。您可以在高级设置中配置此设置。

​
支持的数据格式

支持的格式如下：

​
支持的数据类型

​
标准类型

ClickPipes 当前支持以下标准 ClickHouse 数据类型：
  • 基础数值类型 - [U]Int8/16/32/64、Float32/64 和 BFloat16
  • 大整数类型 - [U]Int128/256
  • Decimal 类型
  • Boolean
  • String
  • FixedString
  • Date、Date32
  • DateTime、DateTime64 (仅支持 UTC 时区)
  • Enum8/Enum16
  • UUID
  • IPv4
  • IPv6
  • Time、Time64
  • JSON
  • 所有 ClickHouse LowCardinality 类型
  • Map，其键和值可使用上述任意类型 (包括 Nullable)
  • Tuple 和 Array，其元素可使用上述任意类型 (包括 Nullable，仅支持一层深度)
  • SimpleAggregateFunction 类型 (适用于 AggregatingMergeTree 或 SummingMergeTree 目标端)

​
Variant 类型支持

ClickPipes 在以下情况下支持 Variant 类型：
  • Avro Union 类型。如果你的 Avro schema 包含一个由多个非 NULL 类型组成的 union，ClickPipes 会推断出合适的 Variant 类型。除此之外，Avro 数据不支持 Variant 类型。
  • JSON 字段。你可以为源数据流中的任何 JSON 字段手动指定 Variant 类型 (例如 Variant(String, Int64, DateTime)) 。不支持复杂子类型 (Array/Map/Tuple) 。此外，由于 ClickPipes 判定应使用哪种 Variant 子类型的方式所限，在 Variant 定义中只能使用一种整数类型或 datetime 类型——例如，不支持 Variant(Int64, UInt32)。

​
JSON 类型支持

ClickPipes 在以下情况下支持 JSON 类型：
  • Avro Record 和 Protobuf Message 字段始终可以映射到 JSON 列。
  • 如果 Avro 字段实际包含 JSON String 对象，则 Avro String 和 Bytes 字段可以映射到 JSON 列。
  • 如果 Protobuf 字段实际包含 JSON String 对象，则 Protobuf String 和 Bytes kind 可以映射到 JSON 列。
  • 始终为 JSON 对象的 JSON 字段可以映射到目标端 JSON 列。
请注意，你需要手动将目标端列更改为所需的 JSON 类型，包括任何固定或跳过的路径。

​
Avro

​
支持的 Avro 数据类型

ClickPipes 支持所有 Avro 基本类型和复杂类型，以及除 local-timestamp-millis 和 local_timestamp-micros 之外的所有 Avro 逻辑类型。Avro record 类型会转换为 Tuple，array 类型会转换为 Array，map 类型会转换为 Map (仅支持字符串键) 。通常可使用此处列出的转换方式。我们建议对 Avro 数值类型使用精确的类型匹配，因为 ClickPipes 在类型转换时不会检查是否发生溢出或精度损失。或者，所有 Avro 类型也都可以插入到 String 列中，此时会表示为有效的 JSON 字符串。

​
Nullable 类型和 Avro union

Avro 中的 Nullable 类型通过 (T, null) 或 (null, T) 形式的 union schema 定义，其中 T 是基础 Avro 类型。在 schema inference 期间，这类 union 会被映射为 ClickHouse 的 Nullable 列。请注意，ClickHouse 不支持 Nullable(Array)、Nullable(Map) 或 Nullable(Tuple) 类型。这些类型的 Avro null union 会被映射为对应的非 Nullable 版本 (Avro Record 类型会映射为 ClickHouse 的命名 Tuple) 。对于这些类型，Avro 中的 “null” 会被 insert 为：
  • 对于 null Avro array，insert 为空 Array
  • 对于 null Avro Map，insert 为空 Map
  • 对于 null Avro Record，insert 为所有字段均使用默认值/零值的命名 Tuple

​
Protobuf

​
支持的 Protobuf 数据类型

ClickPipes 支持所有 Protobuf 2 和 3 类型，唯一的例外是早已弃用的 proto 2 group 类型。基础类型转换使用以下映射：
还支持所有基础类型的 Array、Map 和 Nullable 变体。
对于数值类型，建议使用精确匹配，以避免溢出或精度损失。
还支持以下知名类型：

​
Protobuf oneof

在 schema inference 过程中，Protobuf oneof 字段默认会映射为具名 Tuple，其中最多只有一个字段会包含非默认值。这些字段也可以自动映射为 Variant 列，此时生效的值将采用已设置的组成字段的类型。或者，也可以将每个组成字段手动映射到各自独立的 ClickHouse 列；由于 oneof 字段彼此互斥，因此每条记录中始终只会有一列被赋值。

​
消息列表

如果为 ClickPipe 定义的顶层 Protobuf schema 只包含一个 repeated 字段，且该字段本身是一个 protobuf Message，则 schema inference 和列映射将基于该“被包含”的 Message 字段。Kafka 消息会按此类消息列表进行处理，而单条 Kafka 消息会展开为多行 ClickHouse 数据。

​
Kafka 虚拟列

以下虚拟列适用于兼容 Kafka 的流式数据源。创建新的目标端时，可以使用 Add Column 按钮将虚拟列添加到目标表中。 请注意，_raw_message 列仅建议用于 JSON 数据。 对于只需要 JSON 字符串的使用场景 (例如使用 ClickHouse JsonExtract* 函数来 填充下游 materialized view) ，删除所有“非虚拟”列可能会提升 ClickPipes 性能。

​
结构化消息键

将 _key 映射到 String 列会存储原始 Kafka 消息键。此映射会跳过键解码和 schema 查找。要从结构化键中提取字段，请映射以 _key. 开头的源字段。例如，对于 JSON 键 {"customer":{"id":42}}，可将 _key.customer.id 映射到 customer_id 等目标端列。 对于 _key.* 映射，或将 _key 直接映射到 String 以外类型的情况，ClickPipes 会先检查该键是否使用配置的 Schema Registry 编码。如果未使用，ClickPipes 会检查该键是否为 JSON 对象。使用 registry 编码的键必须与记录值使用相同的格式和 registry 家族，但可以使用不同的 schema ID。键的 schema 变更会自动检测。 启用解码后，原始键、JSON 标量或数组以及格式错误的 JSON 都不会填充嵌套键字段；相应的目标端列会使用该类型的默认值。如果 ClickPipes 识别出使用 registry 编码的键，但无法获取或应用其 schema，则会将 Kafka 记录写入 ClickPipes error table。 Avro 键还可以使用非记录根 schema，例如基本类型、数组、map 或 fixed 类型。要解码此类键，请将 _key 直接映射到 String 以外的兼容目标类型。非记录 schema 无法填充嵌套键字段。
最后修改于 2026年8月18日