> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> AvroConfluent 格式文档

# AvroConfluent

| 输入 | 输出 | 别名 |
| - | - | - |
| ✔ | ✔ | |

## 描述

[Apache Avro](https://avro.apache.org/) 是一种面向行的序列化格式，使用二进制编码来高效处理数据。`AvroConfluent` 格式支持借助 [Confluent Schema Registry](https://docs.confluent.io/current/schema-registry/index.html) (或与其 API 兼容的服务) 读取和写入采用 Avro 编码的消息。

每条消息都使用 Confluent 传输格式：一个魔数字节 (`0x00`) ，后跟一个 4 字节大端序的 schema ID，再后跟 Avro 二进制数据。读取时，ClickHouse 会通过查询 registry 来解析 schema ID。写入时，ClickHouse 会注册根据输出列推导出的 schema，并将生成的 ID 添加到每一行前面。为获得最佳性能，schema 会被缓存。

<a id="data-types-matching" />

## 数据类型映射

下表列出了 Apache Avro format 支持的所有 数据类型，以及它们在 `INSERT` 和 `SELECT` queries 中对应的 ClickHouse [数据类型](/zh/reference/data-types/index)。

| Avro data type `INSERT` | ClickHouse data type | Avro data type `SELECT` |
| - | - | - |
| `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](/zh/reference/data-types/int-uint), [UInt(8\16\32)](/zh/reference/data-types/int-uint) | `int` |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](/zh/reference/data-types/int-uint), [UInt64](/zh/reference/data-types/int-uint) | `long` |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](/zh/reference/data-types/float) | `float` |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](/zh/reference/data-types/float) | `double` |
| `bytes`, `string`, `fixed`, `enum` | [String](/zh/reference/data-types/string) | `bytes` 或 `string` \* |
| `bytes`, `string`, `fixed` | [FixedString(N)](/zh/reference/data-types/fixedstring) | `fixed(N)` |
| `enum` | [Enum(8\16)](/zh/reference/data-types/enum) | `enum` |
| `array(T)` | [Array(T)](/zh/reference/data-types/array) | `array(T)` |
| `map(V, K)` | [Map(V, K)](/zh/reference/data-types/map) | `map(string, K)` |
| `union(null, T)`, `union(T, null)` | [Nullable(T)](/zh/reference/data-types/date) | `union(null, T)` |
| `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](/zh/reference/data-types/variant) | `union(T1, T2, …)` \*\* |
| `null` | [Nullable(Nothing)](/zh/reference/data-types/special-data-types/nothing) | `null` |
| `int (date)` \*\*\* | [Date](/zh/reference/data-types/date), [Date32](/zh/reference/data-types/date32) | `int (date)` \*\*\* |
| `long (timestamp-millis)` \*\*\* | [DateTime64(3)](/zh/reference/data-types/datetime) | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\* | [DateTime64(6)](/zh/reference/data-types/datetime) | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\* | [DateTime64(N)](/zh/reference/data-types/datetime) | `bytes (decimal)`  \*\*\* |
| `int` | [IPv4](/zh/reference/data-types/ipv4) | `int` |
| `fixed(16)` | [IPv6](/zh/reference/data-types/ipv6) | `fixed(16)` |
| `bytes (decimal)` \*\*\* | [Decimal(P, S)](/zh/reference/data-types/decimal) | `bytes (decimal)` \*\*\* |
| `string (uuid)` \*\*\* | [UUID](/zh/reference/data-types/uuid) | `string (uuid)` \*\*\* |
| `fixed(16)` | [Int128/UInt128](/zh/reference/data-types/int-uint) | `fixed(16)` |
| `fixed(32)` | [Int256/UInt256](/zh/reference/data-types/int-uint) | `fixed(32)` |
| `record` | [Tuple](/zh/reference/data-types/tuple) | `record` |

* `bytes` is default, controlled by setting [`output_format_avro_string_column_pattern`](/zh/reference/settings/formats/output-format#output_format_avro_string_column_pattern)

\*\*  [Variant 类型](/zh/reference/data-types/variant) 会隐式地接受 `null` 作为字段值，因此，例如 Avro 的 `union(T1, T2, null)` 会被转换为 `Variant(T1, T2)`。
因此，当从 ClickHouse 生成 Avro 时，我们必须始终在 Avro 的 `union` 类型集合中包含 `null` 类型，因为在进行 schema inference 时，我们无法判断是否有某个值实际为 `null`。

\*\*\* [Avro 逻辑类型](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

不受支持的 Avro 逻辑类型：

* `time-millis`
* `time-micros`
* `duration`

## 格式设置

[//]: # "NOTE 这些设置也可以在会话级别设置，但这种用法并不常见，过于突出地说明这一点可能会让用户感到困惑。"

| Setting | Description | Default |
| - | - | - |
| `input_format_avro_allow_missing_fields` | 当 schema 中找不到某个字段时，是否使用默认值而不是报错。 | `0` |
| `input_format_avro_null_as_default` | 当向不可为空的列中插入 `null` 值时，是否使用默认值而不是报错。 | `0` |
| `format_avro_schema_registry_url` | Confluent Schema Registry 的 URL。对于基本身份验证，可以将经过 URL 编码的凭据直接包含在 URL 路径中。 | |
| `format_avro_schema_registry_connection_timeout` | Schema Registry HTTP 客户端的连接超时时间 (秒) ，用于 schema 拉取和注册。必须大于 0；若取值为 600 (10 分钟) 或更大，则会被降为 599。 | `1` |
| `format_avro_schema_registry_send_timeout` | Schema Registry HTTP 客户端的发送超时时间 (秒) 。必须大于 0；若取值为 600 (10 分钟) 或更大，则会被降为 599。 | `1` |
| `format_avro_schema_registry_receive_timeout` | Schema Registry HTTP 客户端的接收超时时间 (秒) 。必须大于 0；若取值为 600 (10 分钟) 或更大，则会被降为 599。 | `1` |
| `output_format_avro_confluent_subject` | 用于输出：schema 在 Schema Registry 中注册时使用的 subject 名称。写入时必填。 | |
| `output_format_avro_string_column_pattern` | 用于输出：将 String 列序列化为 Avro `string` 的正则表达式 (默认为 `bytes`) 。 | |

## 示例

### 从 Kafka 读取

要使用 [Kafka 表引擎](/zh/reference/engines/table-engines/integrations/kafka) 读取采用 Avro 编码的 Kafka topic，请使用 `format_avro_schema_registry_url` 设置指定 Schema Registry 的 URL。

```sql theme={null}
CREATE TABLE topic1_stream
(
    field1 String,
    field2 String
)
ENGINE = Kafka()
SETTINGS
kafka_broker_list = 'kafka-broker',
kafka_topic_list = 'topic1',
kafka_group_name = 'group1',
kafka_format = 'AvroConfluent',
format_avro_schema_registry_url = 'http://schema-registry-url';

SELECT * FROM topic1_stream;
```

### 写入 Kafka

要将 AvroConfluent 消息写入 Kafka topic，需要同时设置 Schema Registry URL 和 subject 名称。首次写入时，schema 会自动注册到 registry。

```sql theme={null}
CREATE TABLE topic1_sink
(
    field1 String,
    field2 String
)
ENGINE = Kafka()
SETTINGS
kafka_broker_list = 'kafka-broker',
kafka_topic_list = 'topic1',
kafka_format = 'AvroConfluent',
format_avro_schema_registry_url = 'http://schema-registry-url',
output_format_avro_confluent_subject = 'topic1-value';

INSERT INTO topic1_sink VALUES ('hello', 'world');
```

#### 使用基本身份验证

如果您的 Schema Registry 需要使用基本身份验证 (例如您使用的是 Confluent Cloud) ，可以在 `format_avro_schema_registry_url` 设置中提供经过 URL 编码的凭据。

```sql theme={null}
CREATE TABLE topic1_stream
(
    field1 String,
    field2 String
)
ENGINE = Kafka()
SETTINGS
kafka_broker_list = 'kafka-broker',
kafka_topic_list = 'topic1',
kafka_group_name = 'group1',
kafka_format = 'AvroConfluent',
format_avro_schema_registry_url = 'https://<username>:<password>@schema-registry-url';
```

## 故障排除

要监控摄取进度并排查 Kafka 消费者错误，可以查询 [`system.kafka_consumers` 系统表](/zh/reference/system-tables/kafka_consumers)。如果你的部署包含多个副本 (例如 ClickHouse Cloud) ，则必须使用 [`clusterAllReplicas`](/zh/reference/functions/table-functions/cluster) 表函数。

```sql theme={null}
SELECT * FROM clusterAllReplicas('default',system.kafka_consumers)
ORDER BY assignments.partition_id ASC;
```

如果遇到 schema 解析方面的问题，可以使用 [kafkacat](https://github.com/edenhill/kafkacat) 配合 [clickhouse-local](/zh/concepts/features/tools-and-utilities/clickhouse-local) 进行故障排查：

```bash theme={null}
$ kafkacat -b kafka-broker  -C -t topic1 -o beginning -f '%s' -c 3 | clickhouse-local   --input-format AvroConfluent --format_avro_schema_registry_url 'http://schema-registry' -S "field1 Int64, field2 String"  -q 'select *  from table'
1 a
2 b
3 c
```