dbt - Documentation

Documentation Website

Rendering and using the docs site for your project

Auto-generated dbt docs

dbt ships with a built-in documentation website for your dbt project. You can view this documentation site for your project at any time by running the following commands:

dbt docs generate
dbt docs serve

More information about these commands and the resulting docs site are provided below. When these commands are run in order, you'll be presented with a new browser tab that might look something like this:

Auto-generated dbt documentation website

Auto-generated dbt documentation website

The docs site

The auto-generated dbt docs website is a single page application that renders all of the information dbt has about your project into an single interface. The website itself a single index.html file. When you run dbt compile and dbt docs generate, dbt will output json files used to power the docs site. These files live in the target/ directory. They are:

manifest.json

This file contains a full representation of your dbt project in a single file. Resources like models, tests, and macros are all represented inside of this file. The docs site uses this file to render information about your models, their tests, their relationships, and so on.

This file is generated by running dbt compile.

run_results.json

This file contains information about the last run of dbt. Crucially, it contains the compiled SQL for every model in your project. dbt uses this file to render the compiled sql directly into the documentation site.

This file is generated by running dbt compile.

catalog.json

This file contains information from your data warehouse about the tables and views produced by the models in your project. dbt uses this file to render information like column types and table statistics into the docs site.

This file is generated by running dbt docs generate.

Using the documentation site

The documentation site can be used in basically two different ways. It serves as a resource for discovering and understanding models themselves, as well as understanding the relationships between models.

Documenting models

If you followed along with the Testing and Documentation guides, then your models are annotated with rich descriptions and schema tests. Using the docs interface, you can navigate to the documentation for a specific model. That might look something like this:

Auto-generated documentation for a dbt model

Auto-generated documentation for a dbt model

Here, you can see the a representation of the project structure, a markdown description for a model, and a list of all of the columns (with documentation) in the model.

From here, you can click the green button in the bottom-right corner of the webpage to expand a "mini-map" of you DAG. This pane (shown below) will display the immediate parents and children of the model that you're exploring.

Opening the DAG mini-map

Opening the DAG mini-map

In this example, the fct_subscription_transactions model only has one direct parent. By clicking the "Expand" button in the top-right corner of the window, we can pivot the graph horizontally and view the full lineage for our model. This lineage is filterable using the --models and --exclude flags, which are consistent with the semantics of dbt run. Further, you can right-click to interact with the DAG, jump to documentation, or share links to your graph visualization with your coworkers.

The full lineage for a dbt model

The full lineage for a dbt model

Setting a custom overview

The "overview" shown in the documentation 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:

{% docs __overview__ %}

## Data Documentation for [Your Org]

Specific information
 - goes
 - here

{% enddocs %}

Deploying the documentation site

Security

The dbt docs serve command is only intended for local/development hosting of the documentation site. Please use one of the methods listed below (or similar) to ensure that your documentation site is hosted securely!

dbt's documentation website was built in a way that makes it easy to host on the web. The site itself is "static", meaning that you don't need any type of "dynamic" server to serve the docs. Some common methods for hosting the docs are:

  1. dbt Cloud
  2. Host on S3 (optionally with IP Whitelisting)
  3. Publish on Netlify
  4. Spin up a web server like Apache/Nginx

Documentation Website


Rendering and using the docs site for your project

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.