将 dbt ETL 管道迁移到 Databricks 的实践指南

越来越多的数据团队开始把 dbt 的转换任务迁移到 Databricks Lakehouse 平台上运行。这种组合——dbt 负责声明式的数据转换逻辑，Databricks 提供统一的湖仓存储与计算引擎——正在成为现代数据栈的主流配置之一。本文梳理将现有 dbt ETL 管道重新指向 Databricks 的关键步骤与注意事项。

说明：本文基于有限的原始素材撰写，部分内容为结合行业通用实践的补充性解读，具体实施请以官方文档为准。

为什么选择 dbt + Databricks 组合

dbt（data build tool）的核心价值在于用 SQL 和 Jinja 模板管理数据转换，把软件工程的最佳实践（版本控制、测试、文档、模块化）带入数据建模环节。而 Databricks Lakehouse 则统一了数据湖的低成本存储与数据仓库的查询性能，底层基于开放的 Delta Lake 格式。

两者结合时，dbt 承担「转换层」（即 ELT 中的 T），而 Databricks 提供可弹性伸缩的计算资源和持久化存储。相比把 dbt 跑在传统数仓上，迁移到 Databricks 通常能获得更好的大规模处理能力、更灵活的成本控制，以及对半结构化数据的原生支持。

Delta Lake 是由 Databricks 开源的存储层格式，建立在 Parquet 文件之上，核心特性包括：ACID 事务支持（通过事务日志实现）、可扩展的元数据处理、Time Travel（数据版本回溯）以及 Schema Evolution（模式演化）。它解决了传统数据湖缺乏事务保证、容易产生数据不一致的痛点。在 dbt 的语境下，Delta Lake 意味着 dbt 模型写入的表天然支持 merge/upsert 操作，增量模型的实现比传统对象存储更可靠，同时也能通过 Time Travel 在出现数据质量问题时快速回滚到历史版本。

迁移前的准备工作

在动手「重新指向」（repoint）之前，有几项基础工作需要就绪：

环境与连接配置

核心是替换 dbt 项目中的 adapter 和连接配置。dbt 通过 dbt-databricks 适配器与 Databricks 通信，需要在 profiles.yml 中配置目标集群或 SQL Warehouse 的连接信息，包括 host、HTTP path、access token 以及 catalog 和 schema。

盘点现有模型的 SQL 方言

不同数仓的 SQL 方言存在差异。从 Snowflake、BigQuery 或 Redshift 迁移过来时，需要检查现有模型中使用的函数、数据类型和特定语法，确认它们在 Databricks SQL（基于 Spark SQL）中有对应实现。日期函数、窗口函数和类型转换是最常见的差异点。

核心迁移步骤

安装与配置适配器

首先安装 dbt-databricks 包，并在 profile 中指定 type: databricks。相比早期的 dbt-spark，官方推荐使用 dbt-databricks，它对 Unity Catalog、Delta 表特性有更完整的支持。

Unity Catalog 是 Databricks 推出的统一数据治理层，采用三层命名空间：catalog.schema.table，与传统两层命名空间（schema.table）不同。启用 Unity Catalog 后，数据资产的权限管理、数据血缘追踪和审计日志都在这一层统一处理。对 dbt 用户来说，最直接的影响是 profiles.yml 中必须同时指定 catalog 字段，所有模型引用和 ref() 函数生成的路径也会携带 catalog 前缀。如果团队此前使用 dbt-spark 适配器或在未启用 Unity Catalog 的旧版工作区运行，迁移到 dbt-databricks + Unity Catalog 时需要特别关注命名空间的变化，并相应更新跨库引用的模型。

调整物化策略

Databricks 环境下，dbt 模型的物化方式（materialization）需要重新评估。Delta Lake 支持 table、view、incremental 和 materialized view 等多种物化类型。对于增量模型，可以利用 Delta 的 merge 能力实现高效的 upsert，这往往是迁移后性能优化的关键环节。

dbt 的增量模型（incremental model）通过 is_incremental() 宏判断当前运行是全量刷新还是增量追加。在 Databricks 环境下，配置 incremental_strategy: merge 可以让 dbt 生成基于 Delta Lake MERGE INTO 语句的 upsert 逻辑，即按指定的唯一键匹配已有行并更新，不匹配则插入，避免了传统 insert overwrite 方式的全量重写开销。除 merge 之外，Databricks 还支持 insert_overwrite（按分区覆盖）和 append 策略，选择哪种策略取决于业务对幂等性、数据延迟和计算成本的权衡。对于高频小批量更新场景，merge 策略结合 Delta 的 Z-Order 索引能显著降低扫描范围，进一步提升性能。

验证数据一致性

迁移完成后，务必在新旧环境之间做数据比对，确认转换结果一致。dbt 自带的 test 框架（如 unique、not_null、accepted_values）可以作为基础校验手段，复杂场景则建议编写自定义测试或使用行数、聚合值对比。

常见的坑与优化建议

迁移过程中最容易被忽视的是计算资源选型。Databricks 提供交互式集群、作业集群和 SQL Warehouse 等多种计算形态，dbt 的批量转换任务通常更适合使用 Serverless SQL Warehouse 或作业集群，以平衡成本与启动延迟。

权限与 Catalog 管理也需提前规划。如果启用了 Unity Catalog，dbt 的目标 catalog/schema 需要对应的权限配置，否则模型创建会失败。

此外，建议把迁移当作一次技术债清理的机会：梳理冗余模型、统一命名规范、补全文档和测试，而不是机械地照搬旧逻辑。

小结

将 dbt 管道重新指向 Databricks 并不是简单替换一个连接串，而是涉及适配器配置、SQL 方言适配、物化策略调整和数据验证的系统性工程。只要做好前期盘点和充分测试，dbt + Databricks 的组合能够为数据团队带来可维护性与扩展性的双重提升。