Doc blocks for reusable descriptions in dbt - Mini Project: Build & Apply

Doc blocks for reusable descriptions

📖 Scenario: You are working on a data analytics project using dbt. You want to keep your documentation clear and avoid repeating the same descriptions for columns in multiple models. To do this, you will use doc blocks to create reusable descriptions.

🎯 Goal: Create a doc block with a reusable description and apply it to a column in a dbt model's schema file.

📋 What You'll Learn

Create a doc block named customer_id_description with a clear description text.

Create a schema file with a model named orders.

Use the doc block customer_id_description as the description for the customer_id column in the orders model.

💡 Why This Matters

🌍 Real World

In real data projects, many columns share the same meaning across tables. Using doc blocks avoids repeating descriptions and reduces errors.

💼 Career

Data analysts and engineers use dbt documentation features like doc blocks to maintain clear, consistent, and professional data documentation.

1

Create a doc block with a reusable description

Create a doc block named customer_id_description with the description text: 'Unique identifier for each customer' inside a docs block in your schema.yml file.

dbt

# Your code here to create the doc block named customer_id_description

Hint

Use the docs key at the top level, then add - name: customer_id_description followed by description: "Unique identifier for each customer" with proper indentation (2 spaces for the list item, 4 spaces for description).

2

Create a schema file with a model named orders

Add a model named orders under the models key in the same schema.yml file. Define a column named customer_id inside the columns list for the orders model.

dbt

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

# Your code here to add the orders model with customer_id column

Hint

Under models, add a list item with name: orders and a columns list containing name: customer_id.

3

Use the doc block as the description for the customer_id column

In the orders model's customer_id column, add a description key that uses the doc block customer_id_description with the syntax description: '{{ doc("customer_id_description") }}'.

dbt

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

models:
  - name: orders
    columns:
      - name: customer_id
        # Your code here to add description using doc block

Hint

Use the description key with the value '{{ doc("customer_id_description") }}' exactly as shown.

4

Print the final schema.yml content

Print the entire content of the schema.yml file to verify the doc block and model column description are correctly set.

dbt

# Your code here to print the schema.yml content
print(schema_yml_content)

Hint

Assign the full YAML content as a string to schema_yml_content and print it.

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