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.

Practice

1. What is the main purpose of using doc blocks in dbt?

easy

A. To write descriptions once and reuse them across models

B. To create new database tables automatically

C. To run SQL queries faster

D. To define variables for SQL scripts

Solution

1. Step 1: Understand what doc blocks do

   Doc blocks let you write descriptions once and reuse them in multiple places.

2. Step 2: Identify the main purpose

   This saves time and keeps documentation consistent across your project.

3. Final Answer:

   To write descriptions once and reuse them across models -> Option A

4. Quick Check:

   Doc blocks = reusable descriptions [OK]

Hint: Doc blocks = write once, reuse everywhere [OK]

Common Mistakes:

• Thinking doc blocks create tables
• Confusing doc blocks with SQL performance tools
• Using doc blocks to define variables

2. Which syntax correctly defines a doc block named customer_description in dbt?

easy

A. docs:
customer_description: "Description text here"

B. doc_blocks:
customer_description: "Description text here"

C. doc:
customer_description: "Description text here"

D. docs_block:
customer_description: "Description text here"

Solution

1. Step 1: Recall the correct keyword for doc blocks

   The correct keyword to define doc blocks is docs:.

2. Step 2: Match the syntax

   docs: customer_description: "Description text here" uses docs: followed by the doc block name and description, which is correct.

3. Final Answer:

   docs:\n customer_description: "Description text here" -> Option A

4. Quick Check:

   Define doc blocks with docs: [OK]

Hint: Use 'docs:' to define doc blocks in YAML [OK]

Common Mistakes:

• Using 'doc:' instead of 'docs:'
• Adding extra underscores in keyword
• Misnaming the block keyword

3. Given the following doc block definition:

docs:
  sales_desc: "This model contains sales data aggregated by month."

What will be the output of this Jinja code in a model description?

{{ doc("sales_desc") }}

medium

A. Error: doc block not found

B. {{ doc("sales_desc") }}

C. sales_desc

D. This model contains sales data aggregated by month.

Solution

1. Step 1: Understand what {{ doc("sales_desc") }} does

   This Jinja function inserts the text from the doc block named sales_desc.

2. Step 2: Match the doc block content

   The doc block sales_desc contains the description "This model contains sales data aggregated by month." so that text will be output.

3. Final Answer:

   This model contains sales data aggregated by month. -> Option D

4. Quick Check:

   doc("name") outputs doc block text [OK]

Hint: doc("name") outputs the stored description text [OK]

Common Mistakes:

• Expecting the literal string instead of description
• Confusing doc block name with output
• Assuming an error if doc block exists

4. You wrote this doc block:

docs:
  product_info: "Details about product sales."

But when you use {{ doc("product_info") }} in your model, it shows an error. What is the likely cause?

medium

A. You must define doc blocks inside the model SQL file

B. The doc block name is misspelled in the doc() call

C. Doc blocks cannot contain spaces in descriptions

D. You forgot to run dbt compile before using doc blocks

Solution

1. Step 1: Check common causes of doc block errors

   One common cause is a mismatch between the doc block name and the name used in doc().

2. Step 2: Verify usage rules

   Doc blocks are defined in YAML files, not inside SQL files, and descriptions can have spaces. Running dbt compile is standard but not usually the cause of this error.

3. Final Answer:

   The doc block name is misspelled in the doc() call -> Option B

4. Quick Check:

   Name mismatch causes doc block errors [OK]

Hint: Check spelling of doc block names carefully [OK]

Common Mistakes:

• Defining doc blocks inside SQL files
• Assuming spaces cause errors
• Skipping dbt compile step

5. You want to create a reusable doc block for a customer model description that includes the phrase "Contains customer purchase history." You also want to reuse this description in multiple models. Which steps correctly achieve this?

hard

A. Write the description directly in each model SQL file without doc blocks

B. Create a SQL macro that returns the description text and call it in models

C. Define the doc block under docs: in schema.yml, then use {{ doc("customer_history") }} in model descriptions

D. Use ref() function to link to the description in other models

Solution

1. Step 1: Define reusable description in docs block

   Place the description under docs: in a YAML file like schema.yml with a name like customer_history.

2. Step 2: Reuse description with doc() function

   Use {{ doc("customer_history") }} in the description field of any model to reuse the text.

3. Final Answer:

   Define the doc block under docs: in schema.yml, then use {{ doc("customer_history") }} in model descriptions -> Option C

4. Quick Check:

   docs: + doc() = reusable descriptions [OK]

Hint: Define once in docs:, reuse with doc() in models [OK]

Common Mistakes:

• Writing descriptions repeatedly in SQL files
• Using macros instead of doc blocks for descriptions
• Confusing ref() with doc()