在 dbt Mesh 中安全修改模型：判断破坏性变更…

当你要重命名/删除/改类型 dbt 模型列、或改动被下游模型、exposure、BI 工具依赖的模型时，评估影响范围并安全落地变更。

适用场景

解决思路

1. 先读项目根目录的 dependencies.yml：若含 projects: 键，说明是多项目 mesh，引用上游模型必须用跨项目 ref()。
2. 理解上游数据入口：mesh 中用 ref('upstream_project','model_name') 取代 source()，上游项目已在 dependencies.yml 中声明而非 sources.yml。
3. 当多个上游项目存在同名模型（如都叫 stg_customers）时，必须用双参数 ref() 明确项目名，禁止单参数 ref()。
4. 写新 SQL 前先检索代码库中已有的双参数 ref() 调用，查看上游 YAML 中 access: public 的模型，并确认 ref() 第一参数与上游 dbt_project.yml 的 name 字段大小写完全一致。
5. 确认可引用范围：仅 access: public 可跨项目 ref；protected（默认）仅同项目；private 仅同 group。需要非 public 模型时与上游团队协调放宽权限。
6. 设置跨项目协作前先确认套餐：若 dependencies.yml 已有 projects: 且在用跨项目 ref，说明已是 Enterprise；否则要求用户确认是 dbt Cloud Enterprise 或 Enterprise+，无法确认则不要配置跨项目 ref，改用项目内治理功能（groups、access modifiers、contracts）。
7. 跨项目 ref 语法：ref('upstream_project','model_name') 取最新版本，ref('upstream_project','model_name', v=2) 取指定版本。
8. 治理功能按顺序渐进采用：1) Groups & Access（无需改 schema，先做）→ 2) Contracts（需在 YAML 声明每列及类型）→ 3) Versions（需引入破坏性变更并给消费者迁移时间）→ 4) Cross-Project Refs（需 Enterprise 且上游有成功的生产作业）。
9. YAML 放置规则：在模型属性 YAML 中 access、group、contract 必须嵌套在 config: 下，不能作为顶层属性（否则 Fusion 引擎解析报错）；dbt_project.yml 中用 + 前缀（如 +group: finance）；SQL 文件中用 {{ config(access='public', group='finance') }}。
10. 判断是否加 contract：当模型为 access: public、被其他团队依赖、供给 exposure、或被外部消费者直接查询时加 contract: {enforced: true}。
11. 判断是否版本化：当需要对被依赖模型做破坏性变更（删列、改名、改类型）时版本化，无论是否有 enforced contract；消费者需要迁移窗口（其他团队模型、exposure、看板、直接读表的 BI 工具）时也要版本化。
12. 版本化落地分两次部署：Deploy 1 引入新版本（如 v2）但保持 latest_version 指向旧版本 v1，让外部消费者仍按原名读到旧列，新形状在 model_v2 供迁移；Deploy 2 待所有外部消费者确认迁移后再把 latest_version 升到 2 并给 v1 设 deprecation_date。
13. 保持规范（无后缀）关系指向旧形状，按 dbt 版本择一机制：≥1.12/Fusion 用内置 latest_version_pointer（beta）；≤1.11 用 create_latest_version_view() 宏加项目 post-hook；仅在两者都不可用或用户明确拒绝时才用 config.alias 把旧版本钉到无后缀名。切勿同时用指针/视图与 alias 造成冲突。
14. Deploy 1 后验证迁移窗口确实打开：运行 dbt show --inline "select <old_col> from {{ target.schema }}.<unsuffixed_relation>"，若报 column does not exist 说明 latest_version 提升过早。
15. 按决策树定 access 级别：跨项目引用→public（建议配 contract）；同项目跨 group→protected（默认）；仅小团队内部→private；否则 protected。新模型默认 private，按需放宽。
16. 区分 Contracts 与 Data Tests：Contracts 在构建前强制列名/类型/约束，失败则模型不物化；Data Tests 在构建后校验数据质量与业务规则。
17. 若用户要求给不符合条件的模型加 contract（staging 模型、仍在演进、无外部消费者、动态/pivot 列、ephemeral 物化），应劝阻并解释原因，建议改用 data tests、等待 schema 稳定或更换物化方式。
18. 避免把已跨 group 引用的模型改为 private，否则现有 ref 会报 DbtReferenceError；应先放宽为 protected 或把调用方重构进同一 group。
19. 添加 dependencies.yml 前确保上游项目至少有一次成功的生产部署，因为 dbt Cloud 通过上游 manifest.json 解析跨项目 ref。

适用边界 · 注意事项

• 一般的模型构建或调试（应使用 using-dbt-for-analytics-engineering 技能）
• 模型单元测试（应使用 adding-dbt-unit-test 技能）
• 语义层相关工作（应使用 building-dbt-semantic-layer 技能）