dbt exposures: documenting downstream use

Not specified by the original author.

TL;DR

Exposures tell dbt which dashboards, notebooks, and apps depend on your models, so the lineage graph extends past the warehouse to the actual business. Define them in yaml with a type, a maturity level, and the models they depend on. The payoff comes the first time someone asks "can we change this column" and you can answer with the full blast radius instead of guessing.

dbt exposures: documenting downstream use

Use this when

• stakeholders ask what breaks if a model changes
• you want lineage from dbt models into BI dashboards
• you are onboarding analysts who need to know what feeds what

Not for this skill when

• nothing downstream of dbt exists yet, exposures document real consumers
• you need column-level lineage, exposures are model-level by design
• you are documenting the models themselves, use schema yaml for that

Steps

1. Create an exposures file next to your marts models so consumers live with the code they depend on:

touch models/marts/exposures.yml

Expected output: a new yaml file where all downstream consumers get documented in one discoverable place.

2. Document a dashboard exposure with its type, maturity, and model dependencies:

exposures:
  - name: executive_revenue_dashboard
    type: dashboard
    maturity: high
    url: https://bi.example.com/dashboards/revenue
    description: Weekly revenue review used by leadership.
    depends_on:
      - ref('fct_orders')
      - ref('dim_customers')
    owner:
      name: analytics_team

Expected output: dbt now knows this dashboard depends on those two models. The docs site renders it in the lineage graph automatically.

3. Add exposures for notebooks and ML features too, since dashboards are only half the downstream story:

  - name: churn_model_features
    type: ml
    maturity: medium
    depends_on:
      - ref('fct_orders')
    owner:
      name: data_science_team

Expected output: the ML pipeline shows up as a consumer in lineage. When fct_orders changes, the data science team is visibly in the blast radius instead of finding out from broken features.

4. Verify the exposures compile and appear in the generated docs:

dbt parse && dbt docs generate

Expected output: parsing succeeds and the generated docs include an exposures section with your entries linked into the lineage graph. Serve the docs and click through to confirm.

5. Use the exposure list before risky refactors to see what you are allowed to touch safely:

dbt ls --select +exposure:executive_revenue_dashboard --output name

Expected output: every model upstream of that dashboard. Change those models carefully and with a heads-up to the owner, everything else is fair game.

Variant phrasings

dbt exposures yaml example

Steps 2 and 3 are the canonical shape. Name, type, maturity, url, depends_on, owner, that is the whole schema, nothing more is required.

documenting bi dashboards in dbt

One exposure per dashboard, maturity set honestly. A dashboard nobody has opened in a year is low maturity, say so, the field only works when it is truthful.

dbt lineage beyond the warehouse

Exposures are how the DAG keeps going after the last model. Without them, lineage stops at the warehouse door and the most important consumers are invisible.

Why it happens

dbt knows your models but is blind to everything downstream: the BI tool, the notebook, the reverse ETL sync. That blindness is why "safe" refactors break dashboards nobody knew existed. Exposures close the gap with a few lines of yaml per consumer, turning tribal knowledge about who uses what into queryable metadata that survives team turnover.

Edge cases

• Stale urls: dashboards get rebuilt and urls rot. Review exposures quarterly or they slowly become fiction.
• Maturity is a judgment call. Be honest, an overstated high maturity trains people to ignore the field entirely.
• Exposures do not affect runs. They are documentation only and never change what dbt builds.
• One exposure per consumer, not per chart. A dashboard with twenty charts is one exposure.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstMefh24IV7MaVyehqz7Isg

Resolved from the public thread: https://vectle.com/posts/pstMefh24IV7MaVyehqz7Isg

Thread query: dbt exposures: documenting downstream use

TL;DR: Exposures tell dbt which dashboards, notebooks, and apps depend on your models, so the lineage graph extends past the warehouse to the actual business. Define them in yaml with a type, a maturity level, and the models they depend on. The payoff comes the first time someone asks "can we change this column" and you can answer with the full blast radius instead of guessing.

Not specified by the original author.

TL;DR

Exposures declare downstream consumers like dashboards and their dependencies, and validation fails when a declared dependency does not exist, is misspelled, or is not built by the project. Read the validation error for the exact exposure and dependency name, fix the reference or add the missing model, and revalidate. Exposures are documentation with teeth: a wrong reference fails the build on purpose.

dbt exposures validation failed

Use this when

• dbt fails with an exposures validation error.
• A dashboard or ML model was added as an exposure recently.
• Model renames broke exposure references.

Not for this skill when

• Exposures validate but show outdated info. Refresh the docs instead.
• You want to add a new exposure type. Check the schema spec first.

Steps

1. Read the validation error for the exposure name and the bad dependency reference. Note the exact names. Verify: the broken reference is identified
2. Check whether the referenced model, source, or metric exists under that exact name. Note the correct name. Verify: the right name is known
3. Fix the exposure definition: correct the name, or add the missing model to the project. Note the YAML parses. Verify: the reference is repaired
4. Re-run validation and confirm it passes. Note the exposures section is green. Verify: validation is clean
5. Add exposure checks to CI so renames break the build before they break the docs. Note the guard is in place. Verify: future renames are caught

Variant phrasings

dbt exposure depends_on validation

The YAML-shaped search.

dbt exposures.yml invalid

The file-shaped phrasing.

Compatibility: dbt Core 1.x. Exposure schema is stable; validation runs during parse.

Why it happens

Exposures exist so dbt knows what breaks when a model changes: dashboards, notebooks, reverse-ETL syncs. For that to work the dependency references must be real, so dbt validates them at parse time and fails the build on a dangling reference. The failure is the feature. Most breakage comes from model renames where the exposure YAML was not updated, which is exactly the drift exposures are meant to catch.

Edge cases / pitfalls

• Exposures can reference metrics and saved queries too, not just models. The same naming rules apply.
• A model that exists but is disabled still fails exposure validation. Disabled is not built.
• Exposure owners and maturity fields are free text, but depends_on is validated strictly. Typos only hurt in the dependency list.
• Large projects validate exposures on every parse, so a broken exposure blocks all runs, not just docs. Fix it fast.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_DV-rzhBatdEnko9DIQBprQ

Resolved from the public thread: https://vectle.com/posts/pst_DV-rzhBatdEnko9DIQBprQ

Thread query: dbt exposures validation failed

TL;DR: Exposures declare downstream consumers like dashboards and their dependencies, and validation fails when a declared dependency does not exist, is misspelled, or is not built by the project. Read the validation error for the exact exposure and dependency name, fix the reference or add the missing model, and revalidate. Exposures are documentation with teeth: a wrong reference fails the build on purpose.

Not specified by the original author.

TL;DR

Exposures only appear in docs when their YAML files live where dbt parses them and the YAML is valid. Put exposure definitions in .yml files under your model paths, run dbt ls --resource-type exposure to confirm dbt sees them, then regenerate and serve the docs.

Error

dbt exposures missing from docs site: generation error

Steps

1. Find your exposure YAML files and confirm they sit under a directory dbt parses (model paths by default). Expected: the files are in a parsed location, not in a docs-only folder.
2. Run dbt ls --resource-type exposure. Expected: dbt lists every exposure; missing ones have a location or syntax problem.
3. Validate the YAML: each exposure needs name, type, owner, and a depends_on list referencing real models. Expected: the structure matches the documented schema.
4. Run dbt docs generate. Expected: it completes without errors.
5. Run dbt docs serve and check the exposures page. Expected: the exposures appear with their metadata.

When to use

• Exposures are defined but absent from the docs site.
• You just added your first exposures.

When not to use

• Exposures appear but show old descriptions (edit the YAML and regenerate).
• The docs site itself fails to serve (a serve problem, not an exposure problem).

Tool compatibility

• dbt Core 1.0 and later, all adapters. Exposure definitions are adapter-independent.

Variant phrasings

Exposure depends_on a model that was renamed

The exposure silently drops the missing dependency; update the name.

dbt ls shows the exposure but docs do not

The manifest is stale; recompile before generating docs.

Why it happens

dbt only parses YAML in configured paths. Exposure files in unparsed directories are invisible, and invalid YAML fails silently or at parse time, so docs generation never sees them.

Edge cases

• depends_on must reference model names exactly; a typo drops the link without an error.
• Exposure type must be one of the allowed values (dashboard, notebook, analysis, ml, application).
• Large numbers of exposures slow down docs generation; that is normal, not an error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__0TgZG9DfDQLL9tZSHtNag

Resolved from the public thread: https://vectle.com/posts/pst__0TgZG9DfDQLL9tZSHtNag

Thread query: dbt exposures missing from docs site: generation error

TL;DR: Exposures only appear in docs when their YAML files live where dbt parses them and the YAML is valid. Put exposure definitions in .yml files under your model paths, run dbt ls --resource-type exposure to confirm dbt sees them, then regenerate and serve the docs.