如何将 dbt ETL 管道重新指向 Databricks
内容提要
将现有 dbt 项目迁移到 Databricks 无需重写模型或业务逻辑：更换 dbt-databricks 适配器、配置 profiles.yml、映射三级命名空间，并处理 regexp_substr、div0、object_construct 等 SQL 方言差异；用 dbt-audit-helper 逐模型比对输出，验证后通过 Lakeflow Jobs 调度生产，实现安全切换。
延伸解读
迁移范围：仅转换层，数据需预先就位
本文聚焦于将 dbt 转换层重新指向 Databricks，不涉及数据迁移或 Unity Catalog 设置。前提是源数据已以 Delta 或 Iceberg 表形式落地并注册在 Unity Catalog 中，且目录和模式已存在。若需迁移数据本身，应参考 Databricks 迁移指南或 Lakebridge。明确边界有助于规划增量迁移，避免一次性全量迁移带来的延迟和瓶颈。
SQL 方言差异：常见函数替换与可移植宏
示例模型使用了 regexp_substr、div0 和 object_construct 等方言相关函数，编译时出现错误。修复方式：将 regexp_substr 替换为 Databricks 的 regexp_extract；引入 dbt_utils 包并使用 safe_divide 替代 div0；用 named_struct 替代 object_construct。对于有可移植等价的函数，建议使用 dbt 跨数据库宏（dbt.* 命名空间）编写一次，以便在任意仓库编译。
验证策略：逐模型比对与并行运行
编译通过后，需用 dbt-audit-helper 逐模型比对旧仓库与 Databricks 的输出。在 analyses/compare_fct_orders.sql 中配置比较，运行后检查是否完全匹配。若存在不匹配（如字符串修剪、排序规则或自定义 UDF 行为），可设置 summarize=false 物化样本行，检查主键差异，修复模型或宏后重跑，直至 100% 匹配。建议并行运行两个目标，直到所有模型验证通过再切换。
生产调度与切换：Lakeflow Jobs 与回滚清单
验证后，可使用 Lakeflow Jobs 调度生产，dbt 是 Jobs 中的一等任务类型，无需外部编排器或自定义 Docker 镜像。切换时需遵循清单：保留 profiles.yml 中的旧目标，监控 system.billing.usage 避免双仓库成本，并保持短回滚路径。按 DAG 顺序分批迁移，从源到 staging、intermediate、marts，每批验证后再继续，最后整体切换。
Q&A
如何将现有的 dbt 项目迁移到 Databricks？
迁移 dbt 项目到 Databricks 无需重写模型或业务逻辑。主要步骤包括：安装 dbt-databricks 适配器，在 profiles.yml 中添加 Databricks 目标，映射三级命名空间（catalog.schema.table），处理 SQL 方言差异（如 regexp_substr、div0、object_construct），使用 dbt-audit-helper 逐模型验证输出，最后通过 Lakeflow Jobs 调度生产。
dbt 项目迁移到 Databricks 时如何处理 SQL 方言差异？
常见的 SQL 方言差异及解决方法：1) REGEXP_SUBSTR 在 Databricks 中只支持两个参数，应改用 regexp_extract；2) DIV0 可用 dbt_utils.safe_divide 替代；3) OBJECT_CONSTRUCT 应转换为 named_struct。此外，可使用 dbt 的跨数据库宏（dbt.* 命名空间）编写可移植 SQL，或利用 Genie Code 自动转换。
如何验证 dbt 迁移到 Databricks 后的输出是否正确？
使用 dbt-audit-helper 进行逐行比较。安装 dbt-audit-helper 后，在 analyses 目录下创建比较查询（如 compare_fct_orders.sql），运行并检查 in_a 和 in_b 的差异。如果存在不匹配，可设置 summarize=false 来物化样本行，检查主键差异，修复模型或宏，直到 100% 匹配。
dbt 在 Databricks 上如何调度生产任务？
可以使用 Lakeflow Jobs 调度 dbt 任务。dbt 是 Jobs 中的一等任务类型，无需外部编排器或自定义 Docker 镜像。创建 Job 后，可以同时运行上游数据摄取和下游操作，实现统一管道。
迁移 dbt 到 Databricks 需要哪些前提条件？
前提条件包括：源数据已位于 Databricks（以 Delta 或 Iceberg 表形式存在并注册在 Unity Catalog 中），且目录和模式已创建。此外，需要安装 dbt-databricks 适配器，并配置 profiles.yml 中的连接信息。
如何安全地将 dbt 生产流量切换到 Databricks？
安全切换步骤：1) 保持现有目标不变，添加 Databricks 目标；2) 使用 dbt-audit-helper 逐模型比较输出，确保匹配；3) 在 Databricks 上验证模型和测试通过；4) 通过 Lakeflow Jobs 调度生产；5) 逐步迁移，按 DAG 顺序（源、暂存、中间、集市）分批进行；6) 并行运行两个目标，直到所有模型匹配后再完全切换。
