DuckDB 已内置于 dbt v2
摘要：dbt v2 采用新的 Rust Fusion 引擎，是首个内置 DuckDB 适配器的 dbt 版本。本文介绍如何配置它、如何使用 DuckLake 和 Iceberg 目录，以及如何用 DuckDB 查询 dbt 的 Parquet 元数据；还会介绍其他与 DuckDB 用户有关的 v2 功能，以及迁移到 dbt v2 的方法。
dbt 是许多数据团队用来管理 SQL 转换的工具：你把每个模型写成一条 SELECT 语句，dbt 根据模型之间的引用关系确定执行顺序，在数据库中构建相应的表和视图，并且可以在这个过程中对它们进行测试。
DuckDB 的 dbt 适配器 dbt-duckdb 于 2021 年 8 月 27 日收到第一个拉取请求，到本文写作时，已经在 GitHub 上获得了 1.4 千颗星。从那以后，dbt 用户只需通过 pip 安装一个 Python 包 dbt-duckdb，把它指向一个文件，也就是本地 DuckDB 数据库，就能得到一个可以工作的项目，让模型构建为表和视图，无须注册服务器或数据仓库，也无须为它们付费。
dbt Labs 在 2025 年 5 月宣布新的 Rust Fusion 引擎时，DuckDB 起初并未得到开箱即用的支持。dbt v2 改变了这一点：它内置了 DuckDB 适配器。下面介绍配置方法和其他新变化。
背景
dbt Labs 于 2025 年 5 月 28 日宣布新的 Rust Fusion 引擎。两天后，用户 ran-codes 创建了一个 GitHub issue，请求提供 DuckDB 适配器：
“有一个庞大的社区使用 DuckDB 适配器运行 DBT。就我个人而言，正是因为 dbt-duckdb 工作流程的配置很轻量，我才得以学习并开始使用 DBT。它帮助我跨过了开始使用 DBT 时的学习门槛。”
截至本文写作时，这个 issue 收到了 146 个 ❤️ 和 21 个 👍。如今，适配器已经内置于 dbt v2。
2026 年 6 月 1 日，dbt Labs 发布了 dbt Core 2.0 的首个 alpha 版本。它与 Fusion 建立在同样的基础之上，同时将 Fusion 的很大一部分代码开源。这些代码以 Apache 2.0 许可迁入 dbt-core 仓库，dbt-fusion 仓库则被归档。v2 有两种发行版本，都可以免费安装到本地，而且运行在同一个引擎上。
dbt 2.0.0 于 2026 年 9 月 14 日发布。这个版本还调整了命令行工具的品牌名称：Fusion 和 dbt-core 分别改为 dbt（专有版本）和 dbt-oss（开源版本）。因此，“Fusion” 如今主要指引擎的名称，而你安装的工具直接叫作 dbt。
配置
在 dbt v1 中，适配器是独立的 Python 包。在 v2 中，适配器位于一个 Rust 单体仓库内，通过 ADBC 驱动连接数据库。
在 v2 中，dbt 会在你第一次运行它时自动下载并缓存 DuckDB 驱动。因此，安装 dbt 后无须再添加其他东西。dbt 还发布了 DuckDB 快速入门指南，帮助你在本地运行项目。
基本的 profile 与以前相同：
my_project:
target: dev
outputs:
dev:
type: duckdb
path: ./warehouse.duckdbDuckLake 和 Iceberg 目录
v2 增加了 Python 适配器所不具备的目录支持。dbt 的 DuckDB 文档将它标为“仅适用于 dbt v2”；旧版 Python 适配器则通过 profile 中的 attach 配置块来挂载 DuckLake。
通过 catalogs.yml，你可以配置 DuckLake 和 Iceberg REST 目录，并使用能够感知目录的物化方式。这要求使用 v2 引擎，并启用 use_catalogs_v2 开关；Python 适配器无法使用这项功能。dbt 会为你生成并执行 ATTACH 语句。
在 catalogs.yml 中定义一个 DuckLake 目录：
catalogs:
- name: local_lake
type: ducklake
table_format: default
config:
duckdb:
metadata_path: metadata.ducklake
data_path: s3://my-bucket/lake在 dbt_project.yml 中启用开关，然后在模型中引用该目录：
flags:
use_catalogs_v2: true{{ config(materialized = 'table', catalog_name = 'local_lake') }}
select * from {{ ref('customers') }}上面的示例遵循 DuckDB 的目录支持文档。
以 Parquet 保存 dbt 元数据
v2 还可以把元数据写成 Parquet，作为大型 JSON 文件的替代格式。你可以直接用 DuckDB 查询这些 Parquet 文件，也可以查询那些大型 JSON 文件。
dbt 将它称为 Information Schema（信息模式）。这是 v2 的一项功能，用 Parquet 而非 JSON 保存 manifest。运行 dbt parse --generate-info-schema 会把一组 Parquet 文件写入 target/info_schema/v1/，因此你无须解析 manifest.json 就能列出自己的模型。
dbt 仓库中的测试固定数据也使用同样的产物，因此你无须先运行 dbt，就可以直接用 DuckDB 查询仓库中的一个文件：
SELECT name, materialized, schema_name
FROM 'https://raw.githubusercontent.com/dbt-labs/dbt/main/crates/dbt-docs-server/web/src/test/fixtures/parquet/dbt.models.parquet';上面的查询会列出固定数据中的三个模型，以及每个模型的物化方式和所在的 schema：
┌─────────────────┬──────────────┬─────────────┐
│ name │ materialized │ schema_name │
│ varchar │ varchar │ varchar │
├─────────────────┼──────────────┼─────────────┤
│ my_second_model │ view │ main │
│ my_third_model │ view │ main │
│ my_first_model │ view │ main │
└─────────────────┴──────────────┴─────────────┘为什么要这样做？在大型项目中，JSON 格式的 manifest.json 可能增长到数百兆字节。即便只是回答一个简单的问题，读取它也意味着加载并解析整个文件。（当然，DuckDB 也能处理这种情况。）Parquet 是列式格式，因此 DuckDB 只读取你选择的列，并且可以进行筛选，而不必把全部内容物化到内存中。
这样一来，就可以方便地询问项目本身的情况：哪些模型被物化为表而非视图，每个模型落在哪个 schema 中，或者哪些模型缺少测试。
这对 CI 检查或审计脚本很有用：你可以在整个项目中强制执行约定，而不必启动 dbt 或数据仓库。执行 dbt parse 后，文件就在磁盘上，你可以直接让 DuckDB 读取它们，把项目元数据当成另一份可查询的数据集。
SQL 理解与列级血缘
dbt 模型将 SQL 与 Jinja 模板结合起来。旧版本会把它们编译成查询字符串，却不检查 SQL 本身。v2 引擎则原生理解多种数据库引擎方言的 SQL。这意味着它可以在查询到达数据仓库之前发现无效的列引用和类型不匹配，而不是等到模型在 DuckDB 上运行时才暴露这些问题。
同样的分析还能在本地生成列级血缘，无须拥有 dbt 平台账户。运行 dbt compile，并带上 --generate-info-schema --static-analysis strict，会把一个 dbt.column_lineage 文件写入前面介绍的 Information Schema Parquet 目录。这样，只需一条普通的 DuckDB 查询，就可以追溯每个模型使用了哪些上游列。
更快的本地开发
v2 以编译后的 Rust 二进制文件发行，而不是一组 Python 包，因此运行前无须解析 Python 依赖树。dbt 将这个引擎描述为大型项目快速构建的基础：解析和编译都在这一个原生可执行文件中完成。
dbt 的 VS Code 扩展也建立在同样的 SQL 理解能力之上。在你编辑模型时，它会提供自动补全、悬停信息和行内错误提示。错误因而会直接显示在编辑器中，而不是等查询往返数据仓库后才出现。该扩展发布在 VS Code Marketplace 上。
固定的 DuckDB 版本与原生函数
v2 附带固定版本的 DuckDB，而不再依赖 pip 为 Python 适配器解析出的版本。固定版本使前面介绍的 Iceberg REST 目录读写支持成为可能，因为它依赖那个特定 DuckDB 构建版本提供的功能。
固定某个 DuckDB 版本，还使 dbt 能够把工作下推到数据库中。过去由 SQL 宏承担的一部分适配器逻辑，现在已经实现为原生 DuckDB 扩展函数，例如 array_except，它以 sf_array_except 的名称暴露出来。
迁移
一个风险较低的起步方法，是在仍使用 dbt v1.12 时测试 v2 解析器。v1.12 提供了一个可选择启用的 v2 解析器。dbt 文档将它描述为一种提前发现兼容性问题的方法，可以在完整迁移前使用。运行下面的命令，检查你的项目是否能够完成解析：
dbt parse --use-v2-parser如果能够完成解析，就按照安装指南切换版本。dbt-autofix 包能处理许多必需的改动，此外还有一份 v2 升级指南。
结语
DuckDB 适配器如今已经是 dbt v2 的一部分，无须单独安装。如果你不想迁移，或者暂时不想迁移，Python 版本的 dbt Core 仍然可用。无论选择哪一种，在 DuckDB 上运行 dbt，都意味着你可以在自己的电脑上开发、测试和发布模型。
除了省去单独安装适配器这一步，v2 还为 DuckDB 带来了几项新能力：DuckLake 和 Iceberg 目录支持、以可查询的 Parquet 形式保存元数据、原生 SQL 理解与列级血缘，以及固定版本的 DuckDB 构建。
如果你已经在使用 dbt-duckdb，升级到 v2 就意味着少安装一个包，并且可以在上述能力的基础上继续工作。如果你还没有使用过它，只需安装 dbt 并写上几行 profile 配置，就足以在笔记本电脑上直接开始构建模型，无须服务器或数据仓库。
原文：DuckDB Now Ships inside dbt v2，作者 Geertjan Wielenga，发表于 2026 年 9 月 22 日。本文为中文译文；原文的版本、统计数据和示例输出对应其写作时间。文中的第一人称引语出自 GitHub 用户 ran-codes。
来源为 DuckDB 网站及文档仓库，仓库根目录采用 MIT 许可。许可原文如下：
Copyright 2018-2025 Stichting DuckDB Foundation
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
暂无评论内容