Avro

输入	输出	别名
✔	✔

描述

Apache Avro 是一种面向行的序列化格式，使用二进制编码以实现高效的数据处理。Avro 格式支持读取和写入 Avro 数据文件。此格式期望使用嵌入式模式的自描述消息。如果您使用带有模式注册表的 Avro，请参考 AvroConfluent 格式。

数据类型映射

以下表格展示了 Apache Avro 格式所支持的所有数据类型，以及它们在 INSERT 和 SELECT 查询中对应的 ClickHouse 数据类型。

Avro 数据类型 INSERT	ClickHouse 数据类型	Avro 数据类型 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 是默认设置，由 output_format_avro_string_column_pattern 控制

** Variant 类型 隐式接受 null 作为字段值，因此例如 Avro 的 union(T1, T2, null) 将被转换为 Variant(T1, T2)。因此，当从 ClickHouse 生成 Avro 时，我们必须始终将 null 类型包含到 Avro union 类型集中，因为在模式推断期间，我们不知道任何值是否实际上为 null。

*** Avro 逻辑类型

不支持的 Avro 逻辑数据类型：

• time-millis
• time-micros
• duration

格式设置

设置	描述	默认值
input_format_avro_allow_missing_fields	当模式中未找到字段时，是否使用默认值而不是抛出错误。	0
input_format_avro_null_as_default	当向非可空列插入 null 值时，是否使用默认值而不是抛出错误。	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 文件的根模式必须为 record 类型。

要查找表列与 Avro 模式字段之间的对应关系，ClickHouse 会比较它们的名称。 此比较是区分大小写的，未使用的字段会被跳过。

ClickHouse 表列的数据类型可以与插入的 Avro 数据对应字段不同。在插入数据时，ClickHouse 根据上表解释数据类型，然后 转换 数据为相应的列类型。

在导入数据时，当在模式中未找到某字段且设置 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_]

可以使用 output_format_avro_codec 和 output_format_avro_sync_interval 设置，分别配置 Avro 文件的输出压缩和同步间隔。

推导 Avro 模式

使用 ClickHouse 的 DESCRIBE 函数，您可以快速查看 Avro 文件的推导格式，如以下示例所示。 该示例包括 ClickHouse S3 公共存储桶中可以公开访问的 Avro 文件的 URL：

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