Doc blocks for reusable descriptions in dbt - Practice Problems & Coding Challenges

Challenge - 5 Problems

🧠 Conceptual

intermediate

Understanding the purpose of doc blocks in dbt

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

A To create reusable documentation snippets that can be referenced across models and sources

B To define SQL queries that run before the main model executes

C To write test cases for data quality checks

D To store configuration settings for dbt profiles

💡 Hint

Think about how documentation can be reused efficiently in multiple places.

Doc blocks in dbt allow you to write documentation once and reuse it in multiple models or sources, ensuring consistency and saving time.

❓ Predict Output

intermediate

Output of referencing a doc block in a model description

Given the following doc block and model configuration, what will be the final description of the model?

docs:
  - name: customer_description
    description: "Contains customer demographic information"

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

A Contains customer demographic information

B {{ doc('customer_description') }}

C Error: doc block not found

D No description available

💡 Hint

Remember how doc blocks are referenced inside model descriptions.

The {{ doc('customer_description') }} syntax injects the content of the doc block named customer_description into the model's description.

❓ data_output

advanced

Result of rendering multiple doc blocks in a source description

Consider these doc blocks and a source configuration:

docs:
  - name: source_name_desc
    description: "Source system name"
  - name: source_table_desc
    description: "Table containing sales data"

sources:
  - name: sales_source
    description: "{{ doc('source_name_desc') }} - {{ doc('source_table_desc') }}"

What is the final description of the source sales_source after rendering?

A {{ doc('source_name_desc') }} - {{ doc('source_table_desc') }}

B Source system name - Table containing sales data

C Source system name Table containing sales data

D Error: Cannot concatenate doc blocks

💡 Hint

Check how multiple doc blocks are combined in a string.

Each {{ doc('...') }} is replaced by its description, and the string concatenates them with ' - ' in between.

🔧 Debug

advanced

Identifying the error in doc block usage

What error will occur when running dbt with this model configuration?

models:
  - name: orders
    description: "{{ doc('non_existent_doc') }}"

A Model runs successfully with empty description

B Runtime error: Undefined variable 'non_existent_doc'

C Compilation error: doc block 'non_existent_doc' not found

D Syntax error in model configuration

💡 Hint

What happens if you reference a doc block that does not exist?

dbt raises a compilation error if a referenced doc block is missing, preventing the model from running.

🚀 Application

expert

Creating a reusable doc block for column descriptions

You want to create a reusable doc block for a column named customer_id used in multiple models. Which of the following dbt YAML snippets correctly defines and references this doc block in a model's column description?

A

models:
  - name: orders
    columns:
      - name: customer_id
        description: "{{ docs('customer_id_desc') }}"

B

models:
  - name: orders
    columns:
      - name: customer_id
        description: "Unique identifier for each customer"

docs:
  - name: customer_id_desc
    description: "{{ doc('customer_id_desc') }}"

C

docs:
  - name: customer_id_desc
    description: "Unique identifier for each customer"

models:
  - name: orders
    columns:
      - name: customer_id
        description: "customer_id_desc"

D

docs:
  - name: customer_id_desc
    description: "Unique identifier for each customer"

models:
  - name: orders
    columns:
      - name: customer_id
        description: "{{ doc('customer_id_desc') }}"

💡 Hint

Check the correct syntax for defining and referencing doc blocks in column descriptions.

Doc blocks are defined under docs with a name and description. They are referenced in model columns using {{ doc('name') }}. Option D follows this pattern correctly.

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