working-with-dbt-mesh
Use when changing a dbt model in a way that could break its consumers — renaming, removing, or retyping a column, or changing a model that downstream models, exposures, dashboards, or BI tools depend on — to judge whether the change is breaking and who it affects. Also use when versioning a model (model versions, latest_version, latest_version_pointer, deprecation_date, migration windows), enforcing contracts, setting access or groups, or doing multi-project dbt Mesh work (cross-project refs via dependencies.yml, disambiguating similarly-named models, splitting a monolith). Covers single- and multi-project, and planning or advising as well as implementing.
dbt-labs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh技能说明
name: working-with-dbt-mesh description: Use when changing a dbt model in a way that could break its consumers — renaming, removing, or retyping a column, or changing a model that downstream models, exposures, dashboards, or BI tools depend on — to judge whether the change is breaking and who it affects. Also use when versioning a model (model versions, latest_version, latest_version_pointer, deprecation_date, migration windows), enforcing contracts, setting access or groups, or doing multi-project dbt Mesh work (cross-project refs via dependencies.yml, disambiguating similarly-named models, splitting a monolith). Covers single- and multi-project, and planning or advising as well as implementing. user-invocable: false metadata: author: dbt-labs
Working with dbt Mesh
Core principle: In a mesh project, upstream data comes through ref(), not source(). Every cross-project reference requires the project name. When in doubt, read dependencies.yml first.
When to Use
- Making a potentially breaking change to a model — renaming, removing, or retyping a column — especially when other models, exposures, or BI tools depend on it. Assess the blast radius before changing it, and reach for model versions rather than editing in place.
- Versioning a model (
versions:,latest_version,latest_version_pointer,deprecation_date) — this applies in a single project, not just multi-project setups - Working in a dbt project that references models from other dbt projects
- Resolving ambiguity when multiple upstream projects have similarly-named models (e.g. multiple
stg_models) - Adding model contracts, access modifiers, or groups
- Setting up cross-project references with
dependencies.yml - Splitting a monolithic dbt project into multiple mesh projects
Do NOT use for:
- General model building or debugging (use the
using-dbt-for-analytics-engineeringskill) - Unit testing models (use the
adding-dbt-unit-testskill) - Semantic layer work (use the
building-dbt-semantic-layerskill)
First: Orient Yourself in a Multi-Project Setup
Before writing or modifying any SQL in a project that uses dbt Mesh, follow these steps:
1. Read dependencies.yml
This file at the project root tells you which upstream projects exist:
# dependencies.yml
projects:
- name: core_platform
- name: marketing_platform
If this file has a projects: key, you are in a multi-project mesh setup. Every model you reference from those upstream projects must use cross-project ref().
2. Understand how upstream data gets into this project
In a mesh setup, upstream project models replace what would alternatively be sources:
| Alternative | Mesh multi-project |
|---|---|
{{ source('stripe', 'payments') }} | {{ ref('core_platform', 'stg_payments') }} |
| Data comes from raw database tables | Data comes from another dbt project's public models |
Defined in sources.yml | Declared in dependencies.yml |
The upstream project has already staged and transformed the raw data. Your project builds on top of their public models, not their raw sources.
3. Disambiguate similarly-named models
When multiple upstream projects have models with the same name (e.g. stg_customers in both core_platform and marketing_platform), you must use the two-argument ref():
-- Correct: explicit project name, no ambiguity
select * from {{ ref('core_platform', 'stg_customers') }}
select * from {{ ref('marketing_platform', 'stg_customers') }}
-- WRONG: dbt cannot determine which project's stg_customers you mean
select * from {{ ref('stg_customers') }}
4. Check existing patterns in the codebase
Before writing new SQL:
- Search for existing two-argument
ref()calls to see which upstream projects and models are already in use - Look at the upstream project's YAML for
access: publicmodels — only these are referenceable cross-project - The first argument of
ref()must exactly match thenamefield in the upstream project'sdbt_project.yml(case-sensitive)
5. Know what you can and cannot reference
| Upstream model access | Can you ref() it cross-project? |
|---|---|
access: public | Yes |
access: protected (default) | No — only within the same project |
access: private | No — only within the same group |
If you need a model that isn't public, coordinate with the upstream team to widen its access.
Cross-Project Refs Require dbt Cloud Enterprise
Cross-project ref() and the projects: key in dependencies.yml are only available on dbt Cloud Enterprise or Enterprise+ plans. Before setting up any cross-project collaboration, verify plan eligibility:
- If
dependencies.ymlalready has aprojects:key and the project is actively using cross-project refs — Enterprise is already in place. Proceed. - Otherwise — ask the user to confirm they are on dbt Cloud Enterprise or Enterprise+ before adding
projects:todependencies.ymlor writing new two-argumentref()calls.
If the user cannot confirm the plan level, or confirms they are on a plan below Enterprise, do not set up cross-project refs. Explain that this feature requires upgrading to Enterprise or Enterprise+ and suggest they use the intra-project governance features (groups, access modifiers, contracts) instead.
Cross-Project ref() Syntax
-- Reference an upstream model (latest version)
select * from {{ ref('upstream_project', 'model_name') }}
-- Reference a specific version
select * from {{ ref('upstream_project', 'model_name', v=2) }}
For full cross-project setup details (dependencies.yml, prerequisites, orchestration), see references/cross-project-collaboration.md.
Governance Features
dbt Mesh includes four governance features. These work independently and can be adopted incrementally:
| Feature | Purpose | Key Config | Reference | |---------|---------|------
阅读完整来源 ↗