Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 41 ยท Tests and Documentation

dbt docs, Lineage and Exposures

Generate and serve the dbt documentation site, read the lineage graph, understand manifest and catalog files, and declare exposures for dashboards.

Everything you write in YAML and SQL is turned into a website by two commands. The site lets analysts search models, read descriptions, see which tests protect a column and, most useful of all, follow a lineage graph from raw source to final dashboard. This lesson covers how it is produced, how to read the graph, and how to add the dashboards and apps that sit at the end of it using exposures.

Generating the site

Terminal
dbt docs generate    # compile the project and collect warehouse metadata
dbt docs serve       # host the site locally (default port 8080)

dbt docs generate writes three files into target/:

File Contents
manifest.json Every node in the project: models, tests, sources, macros, config, descriptions, dependencies
catalog.json Column names and types, row counts and sizes, queried from the warehouse
index.html The single-page app that reads the two JSON files

Because the site is static (HTML plus JSON), you can host it anywhere: an object-storage bucket, an internal web server, or dbt Cloud, which hosts docs for you. dbt docs generate --static produces a single self-contained file.

Use --no-compile if the project is already compiled, and --empty-catalog to skip warehouse queries when you only need the manifest.

Reading the lineage graph

Open any model and click the graph icon. Each box is a node, and each arrow comes from a ref() or source() call. Colors show node types: sources, models, seeds, snapshots, tests, exposures.

flowchart LR
  S1["source: shop.orders"] --> A["stg_orders"]
  S2["source: shop.customers"] --> B["stg_customers"]
  A --> C["fct_orders"]
  B --> C
  C --> D["dim_customer_revenue"]
  D --> E["Exposure: Revenue dashboard"]

The same shape as the docs site graph: sources feed staging, staging feeds marts, marts feed dashboards.

The graph supports selector syntax in the bottom filter bar. Type +fct_orders to see everything upstream, fct_orders+ for everything downstream, 1+fct_orders+1 for one level on each side. This is the same selector language as the command line, so what you explore visually you can also run:

Terminal
dbt ls --select +fct_orders
dbt build --select fct_orders+

Why lineage pays off

  • Impact analysis: before renaming a column, look at what is downstream.
  • Debugging: when a dashboard number looks wrong, walk upstream.
  • Onboarding: new teammates grasp the structure in minutes.

Lineage is only as accurate as your ref() calls. A hard-coded table name in SQL (from analytics.stg_orders) creates no edge, so the graph silently loses a link. Always use ref() and source().

Walking a graph with SQL

Under the hood, lineage is a table of edges. Here is a stand-in (not real dbt output) showing how you would list everything downstream of a model with a recursive query:

SQL Stand-in: downstream of a model

Press Run (or Ctrl + Enter) to see the result here.

Changing stg_orders affects fct_orders, dim_customer_revenue and the dashboard. dbt computes the same thing from manifest.json when you run dbt ls --select stg_orders+.

Exposures

An exposure declares something outside dbt that depends on your models: a dashboard, a notebook, an ML pipeline, an application. Exposures sit at the end of the graph and let you say "this dashboard breaks if dim_customer_revenue breaks".

YAML
version: 2

exposures:
  - name: weekly_revenue_dashboard
    label: Weekly revenue
    type: dashboard
    maturity: high
    url: https://bi.example.com/dashboards/42
    description: >
      Revenue by week and country, reviewed in the Monday leadership meeting.
    depends_on:
      - ref('fct_orders')
      - ref('dim_customer_revenue')
    owner:
      name: Dana Analyst
      email: [email protected]

Valid types include dashboard, notebook, analysis, ml and application. Maturity is high, medium or low. The exposure appears in the docs, and you can build exactly what a dashboard needs:

Terminal
dbt build --select +exposure:weekly_revenue_dashboard

That selects the exposure's parents and their ancestors, which is a nice job to run before refreshing a BI extract.

Keeping docs fresh

  • Run dbt docs generate in a scheduled job (see deploying jobs) and publish the output so the site is never stale.
  • Add description coverage checks in CI.
  • Mark deprecated models in their description and consider model versions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which files does dbt docs generate create in target/?

    The manifest describes the project, the catalog describes warehouse columns, and index.html is the site.
  2. 2. Why might a model be missing from the lineage graph?

    Lineage edges come from ref() and source() calls; a raw table name creates no edge.
  3. 3. What is an exposure?

    Exposures describe things outside dbt that depend on your models, so they appear in the graph.
  4. 4. What does dbt build --select +exposure:weekly_revenue_dashboard run?

    The + prefix adds ancestors, so it builds everything the dashboard needs.

Summary

  • dbt docs generate builds manifest.json and catalog.json; dbt docs serve hosts the site.
  • The lineage graph comes from ref() and source(), and uses the same selector syntax as the CLI.
  • Exposures put dashboards and apps in the graph and can be selected with +exposure:name.
  • Publish fresh docs on a schedule.

Next: Materializations: View, Table and Ephemeral