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.