Doc blocks for reusable descriptions in dbt

Introduction

Doc blocks help you write descriptions once and use them many times. This keeps your project neat and easy to update.

You want to explain a common term used in many places.

You need consistent descriptions across multiple models or columns.

You want to save time by writing descriptions only once.

You want to make your documentation easier to maintain.

Syntax

dbt

docs:
  my_description_name: |
    This is the reusable description text.

models:
  - name: my_model
    description: '{{ doc("my_description_name") }}'

Use docs: at the root level to define reusable descriptions.

Use {{ doc("name") }} to insert the description where needed.

Examples

This example defines a description for a customer table and reuses it in the model.

dbt

docs:
  customer_description: |
    This table contains customer details like name and contact info.

models:
  - name: customers
    description: '{{ doc("customer_description") }}'

This example shows how to reuse a description for a column in a model.

dbt

docs:
  order_status_desc: |
    The status of an order, such as pending, shipped, or delivered.

models:
  - name: orders
    columns:
      - name: status
        description: '{{ doc("order_status_desc") }}'

Sample Program

This dbt YAML file defines a reusable description for the products table and uses it in the model's description. It also defines column descriptions directly.

dbt

docs:
  product_desc: |
    This table stores product information including ID, name, and price.

models:
  - name: products
    description: '{{ doc("product_desc") }}'
    columns:
      - name: product_id
        description: 'Unique identifier for each product.'
      - name: product_name
        description: 'Name of the product.'
      - name: price
        description: 'Price of the product in USD.'

Important Notes

Doc blocks improve consistency and reduce errors in documentation.

Remember to run dbt docs generate and dbt docs serve to see your documentation changes.

Summary

Doc blocks let you write descriptions once and reuse them.

This saves time and keeps your docs consistent.

Use docs: to define and {{ doc("name") }} to reuse.