dbt Exposures: What Are They and How to Use Them

If you’re working with data, you’ve probably heard of dbt, the open-source tool that’s revolutionizing analytics engineering. dbt helps you transform raw data in your warehouse into clean, tested, and documented datasets for analytics and business intelligence. But what happens after your models are built? How do you track where your data is actually used? Like dashboards, reports, or machine learning pipelines?

That’s where dbt Exposures come in.

In this article, we’ll break down what dbt Exposures are, why they matter, and how you can use them to supercharge your data lineage, documentation, and change management. We’ll walk through practical examples, best practices, and tips to help you get started—even if you’re new to dbt.

What are dbt Exposures?

dbt Exposures are a feature in dbt that lets you document and track the downstream use of your data models. In simple terms, an exposure is a way to tell dbt, “This dashboard, report, or application depends on these models.”

Think of exposures as the bridge between your data warehouse and the real-world tools and people who use your data. They make your data lineage complete, showing not just how data is transformed, but also how it’s consumed.

Examples of exposures:

• A Looker or Tableau dashboard
• A Jupyter notebook for data science
• A machine learning pipeline
• An internal or external application using your data

Why is this important?

Without exposures, your dbt project’s lineage graph ends at your final model. With exposures, you can see the full picture—from raw data to business impact.

Why Should You Use Exposures?

Complete Data Lineage

Exposures extend your dbt DAG (Directed Acyclic Graph) to include dashboards, reports, and other end-uses. This means you can answer questions like:

• “If I change this model, which dashboards will be affected?”
• “Who owns this dashboard, and how is it used?”

Better Change Management

When you document exposures, you can quickly assess the impact of changes. No more spelunking through BI tools or Slack threads to figure out what might break.

Improved Documentation

Exposures populate a dedicated section in your dbt docs site, making it easy for data consumers to find context about how data is used.

Stakeholder Transparency

By documenting exposures, you show stakeholders that you understand and care about how data is used. This builds trust and makes you a strategic partner, not just a data black box.

Automated Testing and Selection

You can run or test all models that feed into a specific exposure, making it easier to ensure data quality for critical dashboards or applications.

How Do Exposures Work in dbt?

Exposures are defined in YAML files in your dbt project, usually under the models/ directory. Each exposure describes:

• Name: Unique identifier (snake_case)
• Type: How the data is used (dashboard, notebook, analysis, ML, application)
• Owner: Who is responsible for the exposure
• Depends_on: Which models, sources, or metrics power the exposure
• Other properties: Description, maturity, URL, tags, etc.

When you build your dbt docs, exposures appear as nodes in your DAG and have their own section in the documentation.

Manual vs. Automatic Exposures:

• Manual: You write the YAML yourself (most common)
• Automatic: Some BI tools (like Tableau with dbt Cloud) can auto-generate exposures

Step-by-Step: Adding Your First Exposure

Let’s walk through how to add an exposure to your dbt project.

Step 1: Identify the Downstream Use

Pick a dashboard, report, or application that uses your dbt models. For example, a Tableau dashboard called “Executive Revenue Dashboard.”

Step 2: Find the Models It Depends On

List the dbt models (or sources, metrics) that power this dashboard. For example: fct_revenue, dim_date.

Step 3: Create or Edit a YAML File

You can add exposures to any YAML file under models/. Many teams create a dedicated exposures.yml file.

File structure example:

models/
  ├── exposures.yml
  ├── marts/
  │   └── fct_revenue.sql
  │   └── dim_date.sql
  └── ...

Step 4: Write the Exposure Definition

Here’s a real-world example:

version: 2

exposures:
  - name: executive_revenue_dashboard
    type: dashboard
    maturity: high
    url: https://looker.yourcompany.com/dashboards/executive_revenue_dashboard
    description: |
      Executive-facing dashboard showing monthly revenue KPIs.
      Used in monthly reviews for business units and end of month financial reporting.
    depends_on:
      - ref('fct_revenue')
      - ref('dim_date')
    owner:
      name: Joe Analyst
      email: joe.analyst@company.com

Step 5: Build Your dbt Docs

Run:

dbt docs generate
dbt docs serve

Now, your exposure will appear in the documentation, complete with lineage and details.

Code Examples: Exposure YAML Explained

Let’s break down the anatomy of an exposure YAML block.

Minimal Example

version: 2

exposures:
  - name: marketing_dashboard
    type: dashboard
    owner:
      name: Jane Doe
      email: jane.doe@company.com
    depends_on:
      - ref('fct_marketing_performance')

Full Example with All Properties

version: 2

exposures:
  - name: weekly_jaffle_metrics
    label: Jaffles by the Week
    type: dashboard
    maturity: high
    url: https://bi.tool/dashboards/1
    description: >
      Did someone say "exponential growth"?
    depends_on:
      - ref('fct_orders')
      - ref('dim_customers')
      - source('gsheets', 'goals')
      - metric('count_orders')
    owner:
      name: Callum McData
      email: data@jaffleshop.com
    tags: [finance, weekly]
    meta:
      department: finance
      priority: high

Property Reference

For a full list and details, see the official dbt exposure properties documentation.

Best Practices for Using Exposures

1. Document All Critical Dashboards and Reports

Start with your most important BI assets. If a dashboard is used for executive reporting or key business decisions, add an exposure for it.

2. Keep Owners Up to Date

Make sure the owner field is accurate. This helps with accountability and communication.

3. Use Descriptions and URLs

Provide clear descriptions and direct links to dashboards or notebooks. This makes your documentation more useful for everyone.

4. Tag and Organise

Use tags and meta fields to organise exposures by department, business unit, or priority.

5. Automate Where Possible

If you have many dashboards, consider scripting the generation of exposures using your BI tool’s API.

6. Review and Update Regularly

Set a reminder to review exposures periodically, especially after major changes to your BI tools or data models.

Advanced Tips: Automating and Integrating Exposures

1 . Scripted Generation

If you have dozens or hundreds of dashboards, writing exposures by hand can be tedious. Many BI tools (like Looker, Tableau, or Power BI) have APIs that let you list dashboards and their underlying tables. You can write a script to generate exposure YAML files automatically.

Example approach:

• Use the BI tool’s API to fetch dashboard metadata
• Map dashboard tables to dbt models
• Output YAML in the exposures format

2. dbt Cloud Integrations

If you use dbt Cloud, some BI tools (like Tableau) can automatically create exposures for you. This reduces manual work and keeps your lineage up to date.

3. Use Exposures in dbt CLI

You can run or test all models that feed into an exposure using dbt’s selection syntax:

dbt run -s +exposure:executive_revenue_dashboard
dbt test -s +exposure:executive_revenue_dashboard

This is powerful for targeted testing and deployments.

4. Project-Level Configs

You can enable or disable exposures at the project level in dbt_project.yml:

exposures:
  +enabled: true

Common Pitfalls and How to Avoid Them

1. Not Keeping Exposures Up to Date

If you add or remove dashboards, make sure to update your exposures. Outdated exposures can lead to confusion.

2. Missing Owners or Descriptions

Don’t skip the owner or description fields. These are critical for documentation and accountability.

3. Overlooking Non-BI Exposures

Remember, exposures aren’t just for dashboards! Document notebooks, ML pipelines, and applications too.

4. Incorrect depends_on References

Make sure your depends_on list accurately reflects the models powering the exposure. Use ref, source, and metric as needed.

FAQs

Conclusion

dbt Exposures are a powerful, underused feature that can transform your dbt project from a collection of models into a living map of your data’s business impact. By documenting how your data is consumed—whether in dashboards, notebooks, or applications—you gain:

• Complete, actionable data lineage
• Better change management and impact analysis
• Richer documentation for data consumers
• Stronger relationships with stakeholders

Getting started is as simple as writing a few lines of YAML. As your project grows, exposures help you stay organised, transparent, and in control.

Don’t let your data lineage end at your warehouse. Use exposures to show the full story—from raw data to real-world impact.

Further Reading

• dbt Docs: Exposures
• dbt Docs: Exposure Properties