Avro

输入	输出	别名
✔	✔

描述

Apache Avro 是一种面向行的序列化格式，采用二进制编码以实现高效的数据处理。Avro 格式支持读取和写入 Avro 数据文件。该格式要求消息为自描述消息，并内嵌 schema。如果你将 Avro 与 Schema Registry 搭配使用，请参阅 AvroConfluent 格式。

数据类型映射

下表列出了 Apache Avro format 支持的所有数据类型，以及它们在 INSERT 和 SELECT queries 中对应的 ClickHouse 数据类型。

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

bytes is default, controlled by setting output_format_avro_string_column_pattern

** Variant 类型会隐式地接受 null 作为字段值，因此，例如 Avro 的 union(T1, T2, null) 会被转换为 Variant(T1, T2)。因此，当从 ClickHouse 生成 Avro 时，我们必须始终在 Avro 的 union 类型集合中包含 null 类型，因为在进行 schema inference 时，我们无法判断是否有某个值实际为 null。 *** Avro 逻辑类型不受支持的 Avro 逻辑类型：

time-millis
time-micros
duration

格式设置

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`

示例

读取 Avro 数据

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

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

导入的 Avro 文件的根 schema 必须为 record 类型。为了找出表中列与 Avro schema 字段之间的对应关系，ClickHouse 会比较它们的名称。这种比较区分大小写，未使用的字段会被跳过。 ClickHouse 表中列的数据类型可以与插入的 Avro 数据中的对应字段不同。插入数据时，ClickHouse 会根据上表解释数据类型，然后将数据转换为相应的列类型。导入数据时，如果在 schema 中找不到某个字段，并且启用了设置 input_format_avro_allow_missing_fields，则会使用默认值，而不是抛出错误。

写入 Avro 数据

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

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

列名必须满足以下规则：

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

Avro 文件的输出压缩和同步时间间隔可分别通过 output_format_avro_codec 和 output_format_avro_sync_interval 设置进行配置。

推断 Avro schema

使用 ClickHouse DESCRIBE 函数，你可以像下面的示例一样快速查看推断出的 Avro 文件格式。此示例包含一个可公开访问的 Avro 文件 URL，位于 ClickHouse S3 公共 bucket 中：

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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

描述

数据类型映射

格式设置

示例

读取 Avro 数据

写入 Avro 数据

推断 Avro schema

​描述

​数据类型映射

​格式设置

​示例

​读取 Avro 数据

​写入 Avro 数据

​推断 Avro schema

描述

数据类型映射

格式设置

示例

读取 Avro 数据

写入 Avro 数据

推断 Avro schema