0
0
dbtdata~10 mins

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

Choose your learning style9 modes available
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
StepActionEvaluationResult
1Define doc block 'my_description'Store text 'This is a reusable description.'Doc block saved
2Reference '{{ doc('my_description') }}' in model descriptionReplace with stored doc block textModel description set to reusable text
3Compile dbt docsProcess doc blocks and referencesDocumentation site shows model with reusable description
4Reuse doc block in another model or columnReference same doc blockSame description appears without rewriting
💡 All references replaced by doc block text, enabling reuse and consistent documentation
Variable Tracker
VariableStartAfter Step 1After Step 2After Step 3Final
doc('my_description')undefinedThis is a reusable description.This is a reusable description.This is a reusable description.This is a reusable description.
model.descriptionundefinedundefinedThis 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
Test your understanding
Look at the execution_table at step 2, what happens to the model description?
AIt remains '{{ doc('my_description') }}' as a string
BIt is replaced by the reusable description text
CIt becomes empty
DIt 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?
AThis is a reusable description.
BEmpty string
Cundefined
DNull
💡 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?
AIt stays the same as before
BIt becomes undefined
CIt updates to the new doc block text
DIt 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.