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

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

read_avro 函数

该扩展添加了一个 DuckDB 函数 read_avro。该函数可以这样使用

FROM read_avro('some_file.avro');

该函数将 Avro 文件的内容作为 DuckDB 表公开。然后，您可以使用任意 SQL 构造进一步转换此表。

文件 I/O

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

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

应该“直接”工作。

您也可以在一个读取调用中全局匹配多个文件，或者将文件列表传递给函数

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

如果文件名不知何故包含有价值的信息（这在不幸的情况下非常常见），您可以将 filename 参数传递给 read_avro

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

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

模式转换

此扩展会自动将 Avro 模式转换为 DuckDB 模式。**所有** Avro 类型都可以转换，除了 DuckDB 不支持的**递归类型定义**。

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

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

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

实现

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

限制和未来计划

• 此扩展目前在读取单个（大）Avro 文件或读取文件列表时，不利用**并行性**。在后一种情况下添加并行性支持已列入路线图。
• 目前不支持投影或过滤**下推**，但这也在后期计划中。
• 目前不支持 DuckDB 的 Wasm 或 Windows-MinGW 构建，因为 Avro 库依赖项存在问题（再次叹气）。我们计划最终解决这个问题。
• 如上所述，DuckDB 无法表达 Avro 具有的递归类型定义，这不太可能改变。
• 目前不支持允许用户提供单独的 Avro 模式文件。这不太可能改变，我们迄今为止看到的所有 Avro 文件都嵌入了其模式。
• 目前不支持 DuckDB 中其他读取器支持的 union_by_name 标志。这已计划在未来实现。