dbt Mesh and cross-project ref

dbt Mesh is an architectural pattern that splits a monolithic dbt project into multiple domain-owned projects connected through cross-project references. Instead of one massive repository containing thousands of models, each data team develops, tests, and deploys their own independent dbt project while publishing stable public models for other teams to consume.

Monorepo bottlenecks

As data teams grow, housing every transformation in a single repository creates severe operational bottlenecks:

• Graph compilation and parsing can take several minutes on every CLI command.
• Continuous integration runs slow down because changes to shared macros trigger massive test runs.
• Pull request reviews stall because multiple teams constantly touch the same repository files.
• Clear code ownership breaks down when anyone can edit or reference any model.

Splitting models into domain projects, such as finance, marketing, and core platform, restores autonomy to individual teams.

Cross-project dependencies

In a dbt Mesh architecture, upstream teams publish models by marking them with access public and defining an enforced model contract. Downstream projects declare the upstream project as a dependency inside dependencies.yml:

projects:
  - name: core_analytics

Downstream models then query upstream public models using a two-argument ref function:

select
    customer_id,
    order_id,
    order_total
from {{ ref('core_analytics', 'fct_orders') }}

Model contracts and model versioning keep interfaces stable so that the upstream team does not break downstream pipelines when modifying their internal SQL logic.

Operational constraints

Cross-project references require metadata resolution across separate repositories. In practice, cross-project ref resolution requires the dbt platform (dbt Cloud), which maintains a global metadata catalog of compiled manifests across projects.

When running dbt Core locally without the platform metadata service, cross-project compilation cannot resolve remote manifests dynamically. Teams must either synchronize manifest artifacts manually or manage dependencies through traditional package imports.