用途
本技能适用于在 dbt Mesh 多项目环境中修改 dbt 模型，尤其是可能破坏下游消费者的变更，例如重命名、删除或更改列类型，或者修改被下游模型、exposure 或 BI 工具依赖的模型。它帮助你在变更前评估影响范围，并采用模型版本而非直接原地修改。
主要能力
- 多项目定位：指导读取项目根目录的 dependencies.yml，识别上游项目，并理解上游数据通过跨项目 ref() 而非 source() 进入当前项目。
- 跨项目引用：使用双参数 ref('project_name', 'model_name') 引用上游公共模型，支持指定版本 ref('upstream_project', 'model_name', v=2)。
- 消除歧义：当多个上游项目存在同名模型时，强制使用带项目名的 ref()。
- 治理功能：涵盖模型契约（contract）、分组（group）、访问修饰符（access: public/protected/private）和模型版本（versions、latest_version、latest_version_pointer、deprecation_date）。
- 版本化迁移：指导通过两次部署（先引入新版本但保持 latest_version 指向旧版本，待消费者迁移后再提升 latest_version）为外部消费者提供迁移窗口。
- 决策框架：提供何时使用契约、何时版本化、如何选择访问级别的判断依据。
- 常见错误：列出并纠正多项目环境中的典型错误，如使用单参数 ref()、用 source() 引用上游项目数据、将所有模型设为 public、在非破坏性变更上版本化等。
使用方式
- 定位环境：首先读取 dependencies.yml。若存在 projects: 键，则为多项目 mesh 设置，所有来自上游项目的模型引用必须使用跨项目 ref()。
- 理解数据流：上游项目模型替代了原本的 source。例如，使用 {{ ref('core_platform', 'stg_payments') }} 而非 {{ source('stripe', 'payments') }}。
- 消除歧义：当多个上游项目有同名模型时，必须使用双参数 ref()，如 {{ ref('core_platform', 'stg_customers') }}。
- 检查现有模式：搜索已有的双参数 ref() 调用，查看上游项目 YAML 中 access: public 的模型，确保 ref() 第一个参数与上游 dbt_project.yml 中的 name 字段完全匹配（区分大小写）。
- 了解可引用范围：只有 access: public 的模型可跨项目引用；protected（默认）仅限同项目；private 仅限同组。
- 配置治理功能：在模型属性 YAML 中，access、group、contract 必须嵌套在 config: 键下，不能作为顶层属性，否则在 Fusion 引擎中会解析错误。在 dbt_project.yml 中使用 + 前缀，在 SQL 文件中使用 {{ config(access='public', group='finance') }}。
- 采用顺序：建议按 Groups & Access → Contracts → Versions → Cross-Project Refs 的顺序逐步采用。
- 版本化操作：引入新版本时保持 latest_version 指向旧版本，待外部消费者确认迁移后再提升 latest_version 并设置 deprecation_date。使用 dbt show 验证迁移窗口是否真正打开。
适用场景
- 对模型进行可能破坏下游的变更（重命名、删除、更改列类型）。
- 对模型进行版本化，适用于单项目和多项目环境。
- 在引用其他 dbt 项目模型的 dbt 项目中工作。
- 解决多个上游项目存在同名模型的歧义。
- 添加模型契约、访问修饰符或分组。
- 通过 dependencies.yml 设置跨项目引用。
- 将单体 dbt 项目拆分为多个 mesh 项目。
限制
- 不适用于：一般模型构建或调试（应使用 using-dbt-for-analytics-engineering 技能）、模型单元测试（应使用 adding-dbt-unit-test 技能）、语义层工作（应使用 building-dbt-semantic-layer 技能）。
- 跨项目引用需要 dbt Cloud Enterprise 或 Enterprise+ 计划。在设置跨项目协作前必须确认计划资格。若无法确认或确认低于 Enterprise，则不应设置跨项目引用，可改用项目内治理功能（分组、访问修饰符、契约）。
- 契约限制：不适用于 staging 模型、仍在演进的模型、无外部消费者的模型、使用 pivot()/unpivot() 或动态生成列的模型、ephemeral 物化模型。
- 版本化限制：仅用于破坏性变更，不用于新增列或 bug 修复，也不应预防性版本化。
- 版本化本身不创建迁移窗口，latest_version 才创建。引入新版本和提升 latest_version 必须是两次独立部署，中间隔迁移窗口。
- 指针机制选择：dbt ≥ 1.12 / Fusion 使用内置 latest_version_pointer；≤ 1.11 使用 create_latest_version_view() 宏加项目 post-hook；config.alias 仅作为回退，且不能与指针/视图在同一名称上组合使用。
- 资料中未提供具体价格、收费信息，也未提供安装命令或代码示例之外的详细步骤。