Why this matters
As an Analytics Engineer, you need to know the blast radius of a change. dbt exposures let you declare downstream consumers—dashboards, notebooks, ML apps—so you can:
- See which BI assets break if a model changes.
- Notify the right owner when data is delayed or wrong.
- Document critical analytics in your lineage graph.
- Prioritize work by maturity and tags (e.g., executive, finance, growth).
Real work examples
- Before refactoring a fact model, check what dashboards depend on it.
- When a stakeholder reports a metric issue, trace from dashboard exposure back to models.
- During incident review, use exposures to list affected assets and owners.
Concept explained simply
A dbt exposure is a YAML definition that represents something outside dbt that depends on your models or sources (e.g., a Power BI dashboard). It appears on the dbt lineage graph and in docs, but it does not run. Think of exposures as labeled endpoints of your analytics.
Mental model
Imagine your dbt DAG as a factory line. Models are machines. Exposures are the customers at the end of the line holding a ticket that lists which machines produced their product. If you adjust a machine, you instantly see which customers are impacted.
Core fields you should know
- name: Unique name for the exposure.
- type: One of dashboard, notebook, analysis, ml, application.
- owner: name and email (required; who to contact).
- depends_on: A list of ref() and source() dependencies.
- url: Where the asset lives (not clickable here, but include it in YAML).
- description, tags, maturity: Helpful context and prioritization.
- meta: Free-form key-value for your org’s needs (e.g., team, SLA).
Minimal vs. full example
Minimal exposure (works):
exposures:
- name: exec_kpi_dashboard
type: dashboard
owner:
name: Data Team
email: data@example.com
depends_on:
- ref('fct_orders')
Full exposure (recommended):
exposures:
- name: exec_kpi_dashboard
type: dashboard
url: https://bi.example.com/dashboards/exec-kpi
description: Executive KPIs used in weekly leadership.
owner:
name: Data Team
email: data@example.com
maturity: high
tags: [executive, finance]
depends_on:
- ref('fct_orders')
- ref('dim_customers')
meta:
team: analytics
sla_hours: 24
Worked examples
Example 1: BI dashboard exposure
version: 2
exposures:
- name: revenue_health_pbi
type: dashboard
url: https://powerbi.example.com/groups/abc/reports/123
description: Monitors daily revenue and refunds.
owner:
name: Finance Analytics
email: finance-analytics@example.com
maturity: high
tags: [finance, revenue]
depends_on:
- ref('fct_revenue_daily')
- ref('dim_products')
Example 2: Notebook exposure
version: 2
exposures:
- name: churn_research_notebook
type: notebook
url: https://notebooks.example.com/workspaces/retention/churn.ipynb
description: Analyst research on churn drivers.
owner:
name: Growth Analytics
email: growth@example.com
maturity: medium
tags: [retention, research]
depends_on:
- ref('fct_subscriptions')
- source('marketing', 'touchpoints')
Example 3: Application exposure (ML service)
version: 2
exposures:
- name: recommender_service
type: application
url: https://internal.example.com/services/recs
description: Real-time product recommendations API.
owner:
name: ML Platform
email: ml-platform@example.com
maturity: high
tags: [ml, production]
depends_on:
- ref('features_user_product')
- ref('ml_scored_recommendations')
meta:
oncall: #ml-oncall
rto_minutes: 30
How to add exposures (step-by-step)
- Choose file: Open or create a schema YAML near the related models (e.g., models/marts/finance/schema.yml).
- Add exposures key: If not present, add exposures: at the top level (same level as models: and sources:).
- Fill required fields: name, type, owner (name + email).
- Declare dependencies: List every ref() and source() the asset uses. If a dashboard uses multiple models, include them all.
- Enrich: Add url, tags, maturity, description, and meta as needed.
Quick self-check after adding
- Does the exposure show in the lineage graph attached to the right models?
- Can you identify the owner quickly?
- Do tags and maturity reflect business priority?
Validation and troubleshooting
- Run dbt commands in your environment to validate syntax. Typical checks include listing exposures and generating docs.
- If an exposure is missing from lineage, confirm the YAML lives in a path dbt loads and that version: 2 is set.
- If dependencies don’t appear, ensure every model is referenced via ref() and sources via source().
- Keep owners current; a stale email reduces the value of exposures.
Common mistakes and how to self-check
- Omitting depends_on for a model the asset actually uses. Self-check: compare BI query sources with your ref()/source() list.
- Putting exposures under the wrong YAML key level. Self-check: exposures: is at the top level, sibling to models: and sources:.
- Using free-text model names instead of ref(). Self-check: dependencies must use ref('model_name') and source('source_name','table').
- Missing owner email. Self-check: owner must include both name and email.
- Generic names like dashboard1. Self-check: name should be stable, descriptive, and unique.
Exercises
These mirror the tasks in the Exercises section below. Try them here first, then open the solutions only after attempting.
Exercise 1: Create a dashboard exposure
Define an exposure for a Tableau dashboard used by Sales leadership. It depends on fct_orders and dim_customers. Owner is Sales Analytics (sales-analytics@example.com). Include tags [sales, executive], maturity high, and a short description.
Exercise 2: Create a notebook exposure with sources
Define an exposure named payments_audit_notebook of type notebook that depends on ref('stg_payments') and source('stripe','charges'). Owner is Finance Ops (finops@example.com). Include a meta key team: finops.
- Checklist: Includes required fields (name, type, owner).
- Checklist: Uses ref() and source() correctly under depends_on.
- Checklist: Adds maturity/tags/description where relevant.
- Checklist: Lives under exposures: at YAML top level with version: 2 defined.
Practical projects
- Map your top 10 business-critical dashboards with exposures, including owners and maturity. Share the lineage view with stakeholders.
- Add exposures for analyst notebooks used in weekly reports. Tag them with team names and add meta team and sla_hours.
- Create an incident drill: pick a model, simulate a breaking change, and list affected exposures and owners automatically.
Who this is for and prerequisites
Who this is for: Analytics Engineers, BI Developers, and Data Analysts maintaining dashboards and stakeholder-facing assets.
Prerequisites:
- Basic dbt project structure (models, sources, refs).
- Comfort reading YAML.
- Understanding of your BI tool’s datasets and owners.
Learning path
- Before this: dbt models and sources; documentation basics.
- This step: Define exposures for downstream assets and ownership.
- Next: Strengthen governance with tests, freshness checks, and SLAs; automate change review using lineage.
Mini challenge
Pick one dashboard that often triggers questions. Add or update its exposure with accurate depends_on and owner. Then identify one risky upstream model and note who to notify when it changes.
Quick Test
Take the quick test to check understanding. Everyone can take it; sign in if you want your progress saved.
Next steps
- Finish the exercises and run your validations.
- Implement exposures for at least three critical assets in your project.
- Proceed to the quick test to lock in the concepts.