dbt
Beginner 12 min read dbt

dbt Documentation and Lineage

A documentation site that cannot lie

dbt generates a live documentation site from your models: descriptions from YAML, lineage from ref() and source(), and test results. The docs never drift from the code because they are compiled from it.

dbtdocslineagedata catalogdata dictionarydbt docs generate
Prerequisites: What is dbt? Documentation and Lineage
Before we start

What you will learn

  • Describe descriptions and columns in YAML
  • Generate and serve the docs site
  • Read the lineage graph to trace dependencies
Introduction

What is this?

dbt docs build an HTML catalog from the project: every model and source with its YAML descriptions, every column with its docs and tests, and a lineage graph drawn from ref()/source() relationships. Running dbt docs generate recompiles the catalog — it is generated documentation, so it matches the code by construction.

Motivation

Why do you need it?

  • Documentation generated from code cannot drift into fiction.
  • A searchable catalog is the onboarding ramp for new analysts.
  • Lineage turns impact analysis of any change into a glance.
Think about it

Mental model

Imagine

A map that redraws itself whenever roads change

Think of

dbt lineage and docs

dbt docs generate re-renders the catalog every run, so the map always matches the warehouse being described.

Mechanics

How it works

  • Document models and columns in schema YAML.
  • dbt docs generate introspects the project and builds catalog.json.
  • The docs UI renders descriptions, tests, and the lineage graph.
  • Serve the same manifest to data catalogs and BI tool explorers.

YAML descriptions and refs compile into a living catalog.

YAML
Refs
Generate
Serve
Real world

In production

  • Onboarding: analysts read the docs site instead of reverse-engineering tables.
  • Impact analysis: before renaming a column, lineage shows every affected model.
  • Self-serve: BI teams check metric definitions and owners in the catalog.
Guidelines

Best practices

  • Document every mart and every column that needs a decision (units, definitions).
  • Run docs generate in CI and upload the manifest to your data catalog.
  • Include owners and refresh cadence in the model's meta so questions route somewhere.
Watch out

Common mistakes

  • Documenting in a wiki instead of the YAML so the docs rot.
  • Descriptions that rename the column without stating the definition.
  • Never refreshing docs after model changes, then trusting an old catalog.
When things break

Debugging tips

  • If a model is missing from the catalog, its YAML name or path does not match the model.
  • If lineage misses an edge, the model probably references a table by name instead of ref().
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/2
1

dbt docs are generated from

2

To publish docs that stay fresh, run

Go deeper

Official documentation

dbt documentation
docs
dbt docs command
docs