Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 41 ยท Tests and Documentation

Documenting Models with YAML and Doc Blocks

Write dbt documentation that stays useful: model and column descriptions in YAML, reusable doc blocks in Markdown, meta fields and persisting docs to the warehouse.

Code explains how a model works. Documentation explains what it means: what one row represents, which columns are safe to use, what the odd status code stands for. In dbt, documentation lives in the same repository as the SQL, is reviewed in the same pull requests, and becomes a searchable website with dbt docs generate.

Descriptions in YAML

You document models and columns in the properties file next to them:

YAML
version: 2

models:
  - name: fct_orders
    description: >
      One row per order. Cancelled orders are excluded.
      Revenue is in the shop's base currency.
    columns:
      - name: order_id
        description: Primary key, copied from the source system.
        data_tests: [unique, not_null]
      - name: order_total
        description: Sum of line items plus shipping.
      - name: status
        description: "Lifecycle state: pending, shipped or delivered."

Good descriptions say the grain ("one row per order"), the meaning of derived columns, and anything surprising. Bad descriptions repeat the name ("The order id"). A YAML value containing a colon must be quoted, as in the status line above.

You can also describe sources, seeds, snapshots, macros and tests. Documentation for a source column ends up on the source node in the docs site, so analysts see it when they follow lineage back.

Reusing text with doc blocks

The same description often applies to many columns: customer_id appears in five models. Copy-pasting means five places to update. Use a doc block, a Jinja docs tag in any .md file inside your model paths:

MARKDOWN
{% docs customer_id %}
The unique id of a customer, as issued by the shop's checkout system.
It never changes and is safe to join on across all models.
{% enddocs %}

{% docs order_status %}
The lifecycle state of an order:

| status | meaning |
|---|---|
| pending | Paid, not yet packed |
| shipped | Left the warehouse |
| delivered | Confirmed by the carrier |
| cancelled | Voided before shipping |
{% enddocs %}

Reference a block with the doc() function:

YAML
columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"
  - name: status
    description: "{{ doc('order_status') }}"

Markdown tables, links and lists render nicely on the docs site. Doc block names are global within a package, so choose distinctive names.

A page for the project: overview

A special block named __overview__ becomes the landing page of the docs site:

MARKDOWN
{% docs __overview__ %}
# Shop analytics

This project builds the reporting layer for the online shop.
Start with the **marts** folder; staging models are internal.
{% enddocs %}

What documentation can contain

The meta config carries extra, machine-readable facts: owners, PII flags, tiers.

YAML
models:
  - name: dim_customers
    meta:
      owner: "analytics-engineering"
      contains_pii: true
    columns:
      - name: email
        meta:
          pii: true

meta is shown in the docs and available to other tools through manifest.json. Combine it with a CI check (see CI) that fails when a mart column has no description.

Check coverage with SQL

Documentation coverage can be measured. The manifest.json file lists every column and whether it has a description. Here is the same idea on a stand-in table of columns (not real dbt output):

SQL Stand-in: documentation coverage

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

The dbt_project_evaluator package and the dbt-checkpoint pre-commit hooks automate this on the real manifest.

persist_docs: put descriptions in the warehouse

Docs sites are great, but analysts often live in a BI tool or SQL editor. The persist_docs config writes descriptions into the warehouse as table and column comments (on warehouses that support comments):

YAML
models:
  my_project:
    +persist_docs:
      relation: true
      columns: true

Now COMMENT ON COLUMN metadata is visible wherever people browse the schema. This is why short, precise descriptions matter.

SQL Table and column comments (SQLite has no COMMENT ON)

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

Writing descriptions that help

  • Start a model description with its grain: "One row per ...".
  • Explain units and time zones ("UTC", "cents, not dollars").
  • Document the why of filters ("Excludes test accounts").
  • Link related models with plain names; the docs site makes them clickable through lineage.
  • Review documentation changes like code.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How do you reuse one description for many columns?

    A {% docs name %} block in a .md file is referenced with {{ doc('name') }}.
  2. 2. What is a good first sentence of a model description?

    The grain tells readers what one row represents, which is the most important fact about a table.
  3. 3. What does persist_docs do?

    It sets table and column comments so descriptions appear in SQL tools and BI catalogs.

Summary

  • Document models, columns and sources in YAML; start with the grain.
  • Doc blocks in .md files hold reusable, Markdown-formatted text, used via doc().
  • meta stores owners and flags; persist_docs pushes descriptions to the warehouse.
  • Measure coverage in CI from manifest.json.

Next: dbt docs, Lineage and Exposures