description

models/schema.yml
version: 2
models:
- name: model_name
description: markdown_string
columns:
- name: column_name
description: markdown_string

Definition

A user-defined description. Can be used to document:

  • a model, and model columns
  • sources, source tables, and source columns
  • seeds, and seed columns
  • snapshots, and snapshot columns
  • analyses, and analysis columns
  • macros, and macro arguments

These descriptions are used in the documentation website rendered by dbt (see the documentation guide).

Descriptions can include markdown, as well as the doc jinja function.

Examples

Add a simple description to a model and column

models/schema.yml
version: 2
models:
- name: dim_customers
description: One record per customer
columns:
- name: customer_id
description: Primary key

Add a multiline description to a model

You can use YAML block notation to split a longer description over multiple lines:

models/schema.yml
version: 2
models:
- name: dim_customers
description: >
One record per customer. Note that a customer must have made a purchase to
be included in this table — customer accounts that were created but never
used have been filtered out.
columns:
- name: customer_id
description: Primary key.

Use some markdown in a description

You can use markdown in your descriptions, but you may need to quote your description to ensure the YAML parser doesn't get confused by special characters!

models/schema.yml
version: 2
models:
- name: dim_customers
description: "**[Read more](https://www.google.com/)**"
columns:
- name: customer_id
description: Primary key.

Use a docs block in a description

If you have a long description, especially if it contains markdown, it may make more sense to leverage a docs block. A benefit of this approach is that code editors will correctly highlight markdown, making it easier to debug as you write.

models/schema.yml
version: 2
models:
- name: fct_orders
description: This table has basic information about orders, as well as some derived facts based on payments
columns:
- name: status
description: '{{ doc("orders_status") }}'
models/docs.md
{% docs orders_status %}
Orders can be one of the following statuses:
| status | description |
|----------------|---------------------------------------------------------------------------|
| placed | The order has been placed but has not yet left the warehouse |
| shipped | The order has ben shipped to the customer and is currently in transit |
| completed | The order has been received by the customer |
| returned | The order has been returned by the customer and received at the warehouse |
{% enddocs %}

Link to another model in a description

You can use relative links to link to another model. It's a little hacky — but to do this:

  1. Serve your docs site.
  2. Navigate to the model you want to link to, e.g. http://127.0.0.1:8080/#!/model/model.jaffle_shop.stg_stripe__payments
  3. Copy the url_path, i.e. everything after http://127.0.0.1:8080/, so in this case !/model/model.jaffle_shop.stg_stripe__payments
  4. Paste it as the link
models/schema.yml
version: 2
models:
- name: dim_customers
description: "Filtering done based on [stg_stripe__payments](#!/model/model.jaffle_shop.stg_stripe__payments)"
columns:
- name: customer_id
description: Primary key