description

• Models
• Sources
• Seeds
• Snapshots
• Analyses
• Macros

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.

You may need to quote your YAML

Be mindful of YAML semantics when providing a description. If your description contains special yaml characters like curly brackets, colons, or square brackets, you may need to quote your description. An example of a quoted description is shown below.

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