> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Avro 格式的文档

# Avro

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

<div id="description">
  ## 描述
</div>

[Apache Avro](https://avro.apache.org/) 是一种面向行的序列化格式，采用二进制编码以实现高效的数据处理。`Avro` 格式支持读取和写入 [Avro 数据文件](https://avro.apache.org/docs/current/specification/#object-container-files)。该格式要求消息为自描述消息，并内嵌 schema。如果你将 Avro 与 Schema Registry 搭配使用，请参阅 [`AvroConfluent`](/docs/zh/reference/formats/Avro/AvroConfluent) 格式。

<div id="data-type-mapping">
  ## 数据类型映射
</div>

下表列出了 Apache Avro format 支持的所有 数据类型，以及它们在 `INSERT` 和 `SELECT` queries 中对应的 ClickHouse [数据类型](/docs/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)](/docs/zh/reference/data-types/int-uint), [UInt(8\16\32)](/docs/zh/reference/data-types/int-uint) | `int`                            |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](/docs/zh/reference/data-types/int-uint), [UInt64](/docs/zh/reference/data-types/int-uint)               | `long`                           |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](/docs/zh/reference/data-types/float)                                                             | `float`                          |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](/docs/zh/reference/data-types/float)                                                             | `double`                         |
| `bytes`, `string`, `fixed`, `enum`          | [String](/docs/zh/reference/data-types/string)                                                             | `bytes` 或 `string` \*            |
| `bytes`, `string`, `fixed`                  | [FixedString(N)](/docs/zh/reference/data-types/fixedstring)                                                | `fixed(N)`                       |
| `enum`                                      | [Enum(8\16)](/docs/zh/reference/data-types/enum)                                                           | `enum`                           |
| `array(T)`                                  | [Array(T)](/docs/zh/reference/data-types/array)                                                            | `array(T)`                       |
| `map(V, K)`                                 | [Map(V, K)](/docs/zh/reference/data-types/map)                                                             | `map(string, K)`                 |
| `union(null, T)`, `union(T, null)`          | [Nullable(T)](/docs/zh/reference/data-types/date)                                                          | `union(null, T)`                 |
| `union(T1, T2, …)` \*\*                     | [Variant(T1, T2, …)](/docs/zh/reference/data-types/variant)                                                | `union(T1, T2, …)` \*\*          |
| `null`                                      | [Nullable(Nothing)](/docs/zh/reference/data-types/special-data-types/nothing)                              | `null`                           |
| `int (date)` \*\*\*                         | [Date](/docs/zh/reference/data-types/date), [Date32](/docs/zh/reference/data-types/date32)                      | `int (date)` \*\*\*              |
| `long (timestamp-millis)` \*\*\*            | [DateTime64(3)](/docs/zh/reference/data-types/datetime)                                                    | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\*            | [DateTime64(6)](/docs/zh/reference/data-types/datetime)                                                    | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\*                   | [DateTime64(N)](/docs/zh/reference/data-types/datetime)                                                    | `bytes (decimal)`  \*\*\*        |
| `int`                                       | [IPv4](/docs/zh/reference/data-types/ipv4)                                                                 | `int`                            |
| `fixed(16)`                                 | [IPv6](/docs/zh/reference/data-types/ipv6)                                                                 | `fixed(16)`                      |
| `bytes (decimal)` \*\*\*                    | [Decimal(P, S)](/docs/zh/reference/data-types/decimal)                                                     | `bytes (decimal)` \*\*\*         |
| `string (uuid)` \*\*\*                      | [UUID](/docs/zh/reference/data-types/uuid)                                                                 | `string (uuid)` \*\*\*           |
| `fixed(16)`                                 | [Int128/UInt128](/docs/zh/reference/data-types/int-uint)                                                   | `fixed(16)`                      |
| `fixed(32)`                                 | [Int256/UInt256](/docs/zh/reference/data-types/int-uint)                                                   | `fixed(32)`                      |
| `record`                                    | [Tuple](/docs/zh/reference/data-types/tuple)                                                               | `record`                         |

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

\*\*  [Variant 类型](/docs/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`

<div id="format-settings">
  ## 格式设置
</div>

| Setting                                    | Description                                                                               | Default |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- | ------- |
| `input_format_avro_allow_missing_fields`   | 当 schema 中找不到某个字段时，是否使用默认值而不是报错。                                                          | `0`     |
| `input_format_avro_null_as_default`        | 将 `null` 值插入非 Nullable 列时，是否使用默认值而不是报错。                                                   | `0`     |
| `output_format_avro_codec`                 | Avro 输出文件使用的压缩算法。可能的值：`null`、`deflate`、`snappy`、`zstd`。                                   |         |
| `output_format_avro_sync_interval`         | Avro 文件中同步标记的间隔频率 (以字节为单位) 。                                                              | `16384` |
| `output_format_avro_string_column_pattern` | 用于识别参与 Avro 字符串类型映射的 `String` 列的正则表达式。默认情况下，ClickHouse 的 `String` 列会写为 Avro 的 `bytes` 类型。 |         |
| `output_format_avro_rows_in_file`          | 每个 Avro 输出文件的最大行数。达到该限制时，会创建一个新文件 (如果存储系统支持文件拆分) 。                                        | `1`     |

<div id="examples">
  ## 示例
</div>

<div id="reading-avro-data">
  ### 读取 Avro 数据
</div>

要将 Avro 文件中的数据读入 ClickHouse 表：

```bash theme={null}
$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"
```

导入的 Avro 文件的根 schema 必须为 `record` 类型。

为了找出表中列与 Avro schema 字段之间的对应关系，ClickHouse 会比较它们的名称。
这种比较区分大小写，未使用的字段会被跳过。

ClickHouse 表中列的数据类型可以与插入的 Avro 数据中的对应字段不同。插入数据时，ClickHouse 会根据上表解释数据类型，然后将数据[转换](/docs/zh/reference/functions/regular-functions/type-conversion-functions#CAST)为相应的列类型。

导入数据时，如果在 schema 中找不到某个字段，并且启用了设置 [`input_format_avro_allow_missing_fields`](/docs/zh/reference/settings/formats#input_format_avro_allow_missing_fields)，则会使用默认值，而不是抛出错误。

<div id="writing-avro-data">
  ### 写入 Avro 数据
</div>

要将 ClickHouse 表中的数据写入 Avro 文件：

```bash theme={null}
$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro
```

列名必须满足以下规则：

* 以 `[A-Za-z_]` 开头
* 后续只能包含 `[A-Za-z0-9_]`

Avro 文件的输出压缩和同步时间间隔可分别通过 [`output_format_avro_codec`](/docs/zh/reference/settings/formats#output_format_avro_codec) 和 [`output_format_avro_sync_interval`](/docs/zh/reference/settings/formats#output_format_avro_sync_interval) 设置进行配置。

<div id="inferring-the-avro-schema">
  ### 推断 Avro schema
</div>

使用 ClickHouse [`DESCRIBE`](/docs/zh/reference/statements/describe-table) 函数，你可以像下面的示例一样快速查看推断出的 Avro 文件格式。
此示例包含一个可公开访问的 Avro 文件 URL，位于 ClickHouse S3 公共 bucket 中：

```sql theme={null}
DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro', 'Avro');

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```