跳到主要内容
跳到主要内容

Avro

输入输出别名

描述

Apache Avro 是一个行导向的数据序列化框架,在 Apache 的 Hadoop 项目中开发。 ClickHouse 的 Avro 格式支持读取和写入 Avro 数据文件

数据类型匹配

下面的表格显示了 Apache Avro 格式支持的所有数据类型,以及它们在 INSERTSELECT 查询中的对应 ClickHouse 数据类型

Avro 数据类型 INSERTClickHouse 数据类型Avro 数据类型 SELECT
boolean, int, long, float, doubleInt(8\16\32), UInt(8\16\32)int
boolean, int, long, float, doubleInt64, UInt64long
boolean, int, long, float, doubleFloat32float
boolean, int, long, float, doubleFloat64double
bytes, string, fixed, enumStringbytesstring *
bytes, string, fixedFixedString(N)fixed(N)
enumEnum(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, …) **
nullNullable(Nothing)null
int (date) ***Date, Date32int (date) ***
long (timestamp-millis) ***DateTime64(3)long (timestamp-millis) ***
long (timestamp-micros) ***DateTime64(6)long (timestamp-micros) ***
bytes (decimal) ***DateTime64(N)bytes (decimal) ***
intIPv4int
fixed(16)IPv6fixed(16)
bytes (decimal) ***Decimal(P, S)bytes (decimal) ***
string (uuid) ***UUIDstring (uuid) ***
fixed(16)Int128/UInt128fixed(16)
fixed(32)Int256/UInt256fixed(32)
recordTuplerecord

* 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

示例用法

插入数据

要从 Avro 文件插入数据到 ClickHouse 表中:

所输入的 Avro 文件的根模式必须是 record 类型。

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

ClickHouse 表列的数据类型可以与插入的 Avro 数据的相应字段不同。插入数据时,ClickHouse 根据上表解释数据类型,并将数据转换为相应列类型。

在导入数据时,当模式中找不到字段并且设置 input_format_avro_allow_missing_fields 启用时,将使用默认值,而不是抛出错误。

选择数据

要从 ClickHouse 表中选择数据到 Avro 文件:

列名称必须:

  • [A-Za-z_] 开头
  • 仅后跟 [A-Za-z0-9_]

输出 Avro 文件的压缩和同步间隔可以通过设置 output_format_avro_codecoutput_format_avro_sync_interval 配置。

示例数据

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

格式设置

设置描述默认
input_format_avro_allow_missing_fields对于 Avro/AvroConfluent 格式:当架构中未找到字段时,使用默认值而不是错误0
input_format_avro_null_as_default对于 Avro/AvroConfluent 格式:在 null 及非 Nullable 列的情况下插入默认值0
format_avro_schema_registry_url对于 AvroConfluent 格式:Confluent Schema Registry URL。
output_format_avro_codec输出时使用的压缩编解码器。可能的值:'null','deflate','snappy','zstd'。
output_format_avro_sync_interval以字节为单位的同步间隔。16384
output_format_avro_string_column_pattern对于 Avro 格式:选择作为 AVRO 字符串的字符串列的正则表达式。
output_format_avro_rows_in_file文件中的最大行数(如果存储允许)1