Avro
输入 | 输出 | 别名 |
---|---|---|
✔ | ✔ |
描述
Apache Avro 是在 Apache 的 Hadoop 项目中开发的面向行的数据序列化框架。ClickHouse 的 Avro
格式支持读取和写入 Avro 数据文件。
数据类型匹配
下表显示了 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
使用示例
插入数据
要将 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_codec
和 output_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 |