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.

dbt Copilot available in beta

Use dbt Copilot, available in beta, to generate documentation in the dbt Cloud IDE only.

To use dbt Copilot, you must have an active dbt Cloud Enterprise account and either agree to use dbt Labs' OpenAI key or provide your own Open AI API key. Register here or reach out to the Account team to join the private beta.

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

• 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, you'll need to add descriptions to your project resources. To add descriptions to your project, use the description: key in the same files where you declare tests, like so:

models/<filename>.yml

version: 2

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
        tests:
          - unique
          - not_null

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

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 (main source code and source code using duckdb)
• 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, docs)

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:

  version: 2

  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.

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:

  version: 2

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

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

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

How do I access documentation in dbt Explorer?

If you're using dbt Cloud to deploy your project and have the Team or Enterprise plan, you can use dbt Explorer 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 dbt Explorer in dbt Cloud by clicking the Explore link in the navigation. You can have up to 5 read-only users access the documentation for your project.

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

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

Generate documentation for your project by following these steps:

1. Run the dbt docs generate command to compile relevant information about your dbt project and warehouse into manifest.json and catalog.json files, respectively.
2. Ensure you've created the models with dbt run or dbt build to view the documentation for all columns, not just those described in your project.
3. Run the dbt docs serve command if you're developing locally to use these .json files to populate a local website.

After adding descriptions and generating documentation, dbt provides two complementary ways to view documentation:

• dbt Docs: A static documentation site with model lineage, metadata, and documentation that can be hosted on S3, Netlify, or your own web server. Available on dbt Core or dbt Cloud Developer plans.
• dbt Explorer: Builds upon dbt Docs to provide a dynamic, real-time interface with enhanced metadata, customizable views, deeper project insights, and collaboration tools. Available on dbt Cloud Team or Enterprise plans.

For more details on how to view documentation, see View documentation.

Using docs blocks

Docs blocks can contain arbitrary markdown, but they must be uniquely named.

Syntax

To declare a docs block, use the jinja docs tag. Their names may contain:

• uppercase and lowercase letters (A-Z, a-z)
• digits (0-9)
• underscores (_)
• can't start with a digit.

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 %}

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

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

version: 2

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

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

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

Setting a custom overview

Currently available for dbt Docs only.

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 %}

Custom project-level overviews

Currently available for dbt Docs only.

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 %}