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

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 表中

$ 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 时,将使用默认值而不是抛出错误。

选择数据

要将 ClickHouse 表中的数据选择到 Avro 文件中

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

列名必须

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

可以使用设置 output_format_avro_codecoutput_format_avro_sync_interval 分别配置输出 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 │ │ │ │ │ │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

格式设置

设置描述默认值
input_format_avro_allow_missing_fields对于 Avro/AvroConfluent 格式:当在 schema 中找不到字段时,使用默认值而不是报错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 字符串的 String 列的 regexp。
output_format_avro_rows_in_file文件中的最大行数(如果存储允许)1