About documentation

Good documentation for your dbt models will help downstream consumers discover and understand the datasets you curate for them. dbt provides a way to generate documentation for your dbt project and render it as a website.

Tip

Use dbt Wizard to generate documentation in the dbt platform or locally in the CLI.

Related documentation

• Declaring properties
• dbt docs command
• doc Jinja function
• If you're new to dbt, we recommend that you check out our quickstart guide to build your first dbt project, complete with documentation.

Assumed knowledge

• Data tests

Overview

dbt provides a scalable way to generate documentation for your dbt project using descriptions and commands. The documentation for your project includes:

• Information about your project: including model code, a DAG of your project, any tests you've added to a column, and more.
• Information about your data warehouse: including column data types, and table sizes. This information is generated by running queries against the information schema.
• Importantly, dbt also provides a way to add descriptions to models, columns, sources, and more, to further enhance your documentation.

The following sections describe how to add descriptions to your project, generate documentation, how to use docs blocks, and set a custom overview for your documentation.

Adding descriptions to your project

Before generating documentation, add descriptions to your project resources. Add the description: key to the same YAML files where you declare data tests. For example:

models/<filename>.yml

models:
  - name: events
    description: This table contains clickstream events from the marketing website

    columns:
      - name: event_id
        description: This is a unique identifier for the event
        data_tests:
          - unique
          - not_null

      - name: user-id
        quote: true
        description: The user who performed the event
        data_tests:
          - not_null

Report incorrect code

FAQs

Are there any example dbt documentation sites?

Yes!

• Quickstart Tutorial: You can build your own example dbt project in the quickstart guide
• Jaffle Shop: A demonstration project (closely related to the tutorial) for a fictional e-commerce store. Refer to Clone the Jaffle Shop sample project for clone instructions, or view the main source code and source code using DuckDB on GitHub.
• GitLab: Gitlab's internal dbt project is open source and is a great example of how to use dbt at scale (source code)
• dummy-dbt: A containerized dbt project that populates the Sakila database in Postgres and populates dbt seeds, models, snapshots, and tests. The project can be used for testing and experimentation purposes (source code)
• Google Analytics 4: A demonstration project that transforms the Google Analytics 4 BigQuery exports to various models (source code, docs)
• Make Open Data: A production-grade ELT with tests, documentation, and CI/CD (GHA) about French open data (housing, demography, geography, etc). It can be used to learn with voluminous and ambiguous data. Contributions are welcome (source code.

If you have an example project to add to this list, suggest an edit by clicking Edit this page below.

Do I need to add a YAML entry for column for it to appear in the docs site?

Fortunately, no!

dbt will introspect your warehouse to generate a list of columns in each relation, and match it with the list of columns in your .yml files. As such, any undocumented columns will still appear in your documentation!

How do I write long-form explanations in my descriptions?

If you need more than a sentence to explain a model, you can:

1. Split your description over multiple lines using >. Interior line breaks are removed and Markdown can be used. This method is recommended for simple, single-paragraph descriptions:

models:
  - name: customers
    description: >
      Lorem ipsum **dolor** sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat.

Report incorrect code

2. Split your description over multiple lines using |. Interior line breaks are maintained and Markdown can be used. This method is recommended for more complex descriptions:

models:
  - name: customers
    description: |
      ### Lorem ipsum

      * dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      * tempor incididunt ut labore et dolore magna aliqua.

Report incorrect code

3. Use a docs block to write the description in a separate Markdown file.

How do I access documentation in dbt Catalog?

If you're using dbt to deploy your project and have a Starter, Enterprise, or Enterprise+ plan, you can use Catalog to view your project's resources (such as models, tests, and metrics) and their lineage to gain a better understanding of its latest production state.

Access Catalog in dbt by clicking the Catalog link in the navigation. Read-only users can access the documentation for your project — for license availability by plan, refer to dbt pricing.

dbt developer plan and dbt v1 users can use dbt Docs, which generates basic documentation but it doesn't offer the same speed, metadata, or visibility as Catalog.

Can I document things other than models, like sources, seeds, and snapshots?

Yes! You can document almost everything in your project using the description: key. Check out the reference docs on descriptions for more info!

Generating documentation

dbt provides both self-hosted and cloud-hosted solutions to view documentation for your project. Which one you use depends on your dbt version and where you run dbt.

(Applies to dbt v2.0 and later)

Option	What it is	Where you use it	How to generate it
dbt Docs v2	A redesigned, open-source documentation site with Semantic Layer metadata and column-level lineage that you can host anywhere	Locally with dbt v2. Not available in dbt platform	Run dbt docs generate locally. Refer to generate docs locally for steps
dbt Catalog	A dynamic, real-time interface with enhanced metadata, customizable views, deeper project insights, and collaboration tools.	dbt platform Starter, Enterprise, or Enterprise+ plans	Populated automatically when your jobs run with dbt v2. No extra step required!

Sharing docs with stakeholders?

Anyone with a developer or read-only seat can explore your project(s) in Catalog. Add as many read-only seats as you need to share docs with stakeholders, no separate docs site required.

Generate docs locally

(Applies to dbt v2.0 and later)

Using dbt v2, dbt Docs v2 enhances the original v1 static site with a modern, performant catalog. dbt docs generate compiles your project, produces the v2 Parquet artifacts, and writes a static site that the browser queries directly with DuckDB-WASM (WebAssembly), so you don't need a server to view it.

To generate and serve documentation locally:

• Run dbt docs generate to compile your project, write the index, and export the documentation site in a single command.
• Run dbt docs serve to preview the site locally.

dbt Docs v2 availability

dbt Docs v2 only works self-hosted installations of dbt v2. If you're on the dbt platform, use Catalog which is populated automatically when your jobs run with v2. Adding a dbt docs generate step to a job won't produce a static site in dbt platform.

Refer to dbt docs commands for full usage details, and View documentation to get the most out of your project's documentation.

Using docs blocks

Docs blocks provide a robust method for documenting models and other resources using Jinja and markdown. Docs block files can contain arbitrary markdown, but they must be uniquely named.

Syntax

To declare a docs block, use the Jinja docs tag. The name of a docs block can't start with a digit and may contain:

• Uppercase and lowercase letters (A-Z, a-z)
• Digits (0-9)
• Underscores (_)

events.md

{% docs table_events %}

This table contains clickstream events from the marketing website.

The events in this table are recorded by Snowplow and piped into the warehouse on an hourly basis. The following pages of the marketing site are tracked:
 - /
 - /about
 - /team
 - /contact-us

{% enddocs %}

Report incorrect code

In this example, a docs block named table_events is defined with some descriptive markdown contents. There is nothing significant about the name table_events — docs blocks can be named however you like, as long as the name only contains alphanumeric and underscore characters and doesn't start with a numeric character.

Placement

(Applies to dbt v1.12 and later)

Place docs blocks in .md files. You can also use Jinja-style extensions (.md.j2, .md.jinja, .md.jinja2), however these require setting allow_jinja_file_extensions: true in your dbt_project.yml. This enables Jinja-aware syntax highlighting in IDEs that associate these suffixes with Jinja templating.

By default, dbt searches in all resource paths for docs blocks (for example, the combined list of model-paths, seed-paths, analysis-paths, test-paths, macro-paths, and snapshot-paths). You can adjust this behavior using the docs-paths config.

Usage

To use a docs block, reference it from your schema.yml file with the doc() function in place of a markdown string. Using the examples above, the table_events docs can be included in the schema.yml file as shown here:

schema.yml

models:
  - name: events
    description: '{{ doc("table_events") }}'

    columns:
      - name: event_id
        description: This is a unique identifier for the event
        data_tests:
            - unique
            - not_null

Report incorrect code

In the resulting documentation, '{{ doc("table_events") }}' will be expanded to the markdown defined in the table_events docs block.

Setting a custom overview

Availability

This feature is available only in dbt Docs, the generated documentation site for your dbt project.

The "overview" shown in the dbt Docs website can be overridden by supplying your own docs block called __overview__.

• By default, dbt supplies an overview with helpful information about the docs site itself.
• Depending on your needs, it may be a good idea to override this docs block with specific information about your company style guide, links to reports, or information about who to contact for help.
• To override the default overview, create a docs block that looks like this:

models/overview.md

{% docs __overview__ %}
# Monthly Recurring Revenue (MRR) playbook.
This dbt project is a worked example to demonstrate how to model subscription
revenue. **Check out the full write-up [here](https://blog.getdbt.com/modeling-subscription-revenue/),
as well as the repo for this project [here](https://github.com/dbt-labs/mrr-playbook/).**
...

{% enddocs %}

Report incorrect code

Custom project-level overviews

You can set different overviews for each dbt project/package included in your documentation site by creating a docs block named __[project_name]__.

For example, in order to define custom overview pages that appear when a viewer navigates inside the dbt_utils or snowplow package:

models/overview.md

{% docs __dbt_utils__ %}
# Utility macros
Our dbt project heavily uses this suite of utility macros, especially:
- `surrogate_key`
- `test_equality`
- `pivot`
{% enddocs %}

{% docs __snowplow__ %}
# Snowplow sessionization
Our organization uses this package of transformations to roll Snowplow events
up to page views and sessions.
{% enddocs %}

Report incorrect code

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.