Doc blocks for reusable descriptions in dbt - Step-by-Step Execution

Concept Flow - Doc blocks for reusable descriptions

Write doc block with description

↓

Reference doc block in model or column

↓

dbt compiles docs

↓

Docs appear in documentation site

↓

Reuse doc block in multiple places

Create a doc block once, then reference it in models or columns to reuse descriptions easily in dbt documentation.

Execution Sample

dbt

docs:
  - name: my_description
    description: |
      This is a reusable description.

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

Defines a reusable doc block 'my_description' and references it in a model's description.

Execution Table

Step	Action	Evaluation	Result
1	Define doc block 'my_description'	Store text 'This is a reusable description.'	Doc block saved
2	Reference '{{ doc('my_description') }}' in model description	Replace with stored doc block text	Model description set to reusable text
3	Compile dbt docs	Process doc blocks and references	Documentation site shows model with reusable description
4	Reuse doc block in another model or column	Reference same doc block	Same description appears without rewriting

💡 All references replaced by doc block text, enabling reuse and consistent documentation

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
doc('my_description')	undefined	This is a reusable description.	This is a reusable description.	This is a reusable description.	This is a reusable description.
model.description	undefined	undefined	This is a reusable description.	This is a reusable description.	This is a reusable description.

Key Moments - 2 Insights

Why does the model description show the full text instead of '{{ doc('my_description') }}'?

During compilation (see execution_table step 3), dbt replaces '{{ doc('my_description') }}' with the actual text stored in the doc block, so the final docs show the full description.

Can I change the doc block text and have it update everywhere?

Yes, because all references point to the same doc block variable (doc('my_description')), updating it changes all places where it is used (see variable_tracker).

Visual Quiz - 3 Questions

Look at the execution_table at step 2, what happens to the model description?

A It remains '{{ doc('my_description') }}' as a string

B It is replaced by the reusable description text

C It becomes empty

D It causes an error

💡 Hint

Check the 'Evaluation' and 'Result' columns at step 2 in the execution_table

According to variable_tracker, what is the value of doc('my_description') after step 1?

A This is a reusable description.

B Empty string

C undefined

D Null

💡 Hint

Look at the 'doc('my_description')' row and 'After Step 1' column in variable_tracker

If you update the doc block text, what happens to model.description in variable_tracker?

A It stays the same as before

B It becomes undefined

C It updates to the new doc block text

D It causes a compilation error

💡 Hint

Refer to the key_moments explanation about reuse and variable_tracker showing linked values

Concept Snapshot

Doc blocks store reusable descriptions in dbt.
Reference them with '{{ doc('block_name') }}' in models or columns.
During compilation, references are replaced by the stored text.
This avoids repeating descriptions and keeps docs consistent.
Update the doc block once to change all references.

Full Transcript

In dbt, doc blocks let you write a description once and reuse it many times. You define a doc block with a name and text. Then, in your model or column descriptions, you use '{{ doc('block_name') }}' to insert that text. When dbt compiles your project, it replaces these references with the actual text from the doc block. This way, your documentation stays consistent and easy to update. If you change the doc block text, all places using it update automatically. This saves time and avoids mistakes from copying descriptions multiple times.

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()