avro 扩展使 DuckDB 能够读取 Apache Avro 文件。

avro 扩展于 2024 年底作为社区扩展发布，并于 2025 年初成为核心扩展。

read_avro 函数

该扩展添加了一个 DuckDB 函数：read_avro。该函数的使用方式如下

FROM read_avro('some_file.avro');

此函数会将 Avro 文件的内容以 DuckDB 表的形式公开。随后，您可以使用任何任意 SQL 构造来进一步转换此表。

文件 IO

read_avro 函数已集成到 DuckDB 的文件系统抽象中，这意味着您可以直接从例如 HTTP 或 S3 源读取 Avro 文件。例如

FROM read_avro('https://blobs.duckdb.org/data/userdata1.avro');
FROM read_avro('s3://your-bucket/some_file.avro');

应该可以“直接”使用。

您还可以在单次读取调用中对多个文件使用 glob 模式，或者向函数传递文件列表

FROM read_avro('some_file_*.avro');
FROM read_avro(['some_file_1.avro', 'some_file_2.avro']);

如果文件名包含有价值的信息（不幸的是这种情况很常见），您可以向 read_avro 传递 filename 参数

FROM read_avro('some_file_*.avro', filename=true);

这将在结果集中产生一个额外的列，其中包含 Avro 文件的实际文件名。

模式转换

此扩展会自动将 Avro 模式（Schema）转换为 DuckDB 模式。除递归类型定义外，所有 Avro 类型都可以进行转换，因为 DuckDB 不支持递归类型。

类型映射非常直接，除了 Avro 处理 NULL 的“独特”方式。与其他系统不同，Avro 不会将 NULL 视为诸如 INTEGER 等范围内的可能值，而是将 NULL 表示为实际类型与特殊 NULL 类型的并集（Union）。这与 DuckDB 不同，在 DuckDB 中，任何值都可以是 NULL。当然，DuckDB 也支持 UNION 类型，但使用起来会非常繁琐。

此扩展在可能的情况下简化了 Avro 模式：Avro 中任何类型与特殊 null 类型的并集都会被简化为仅非 null 类型。例如，并集类型 ["int","null"] 的 Avro 记录会变为 DuckDB 的 INTEGER，它恰好有时可以是 NULL。同样，仅包含单一类型的 Avro 并集也会转换为它所包含的类型。例如，并集类型 ["int"] 的 Avro 记录也会变为 DuckDB 的 INTEGER。

该扩展还对 Avro 模式进行了“扁平化”处理。Avro 将表定义为根级“记录（record）”字段，这与 DuckDB 的 STRUCT 字段相同。为了更方便地处理，此扩展将单个顶层记录的条目转换为顶层列。

实现

在内部，该扩展使用了“官方” Apache Avro C API，尽管进行了一些微小的修补以允许从内存读取 Avro 文件。

局限性与未来计划

• 目前，该扩展在读取单个（大型）Avro 文件或读取文件列表时，均未使用并行处理。在后者中增加对并行处理的支持已列入路线图。
• 目前不支持投影（projection）或过滤（filter）下推（pushdown），但也计划在后期阶段实现。
• 由于 Avro 库依赖项的问题，目前不支持 DuckDB 的 Wasm 或 Windows-MinGW 构建（再次叹气）。我们计划最终解决此问题。
• 如上所述，DuckDB 无法表达 Avro 具有的递归类型定义，这一点不太可能改变。
• 目前不支持用户提供单独的 Avro 模式文件。这一点不太可能改变，因为我们迄今为止见过的所有 Avro 文件都嵌入了它们的模式。
• 目前不支持 DuckDB 中其他读取器支持的 union_by_name 标志。这已计划在未来实现。