Doc blocks for reusable descriptions in dbt - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is a doc block in dbt?

A doc block in dbt is a reusable piece of documentation that you write once and can reference in multiple places to keep descriptions consistent and easy to maintain.

beginner

How do you define a doc block in dbt?

You define a doc block in a .yml file under the 'docs:' key, giving it a name and a description. For example:

docs:
  customer_description:
    description: 'Details about the customer table and its purpose.'

beginner

How can you use a doc block in a model or column description?

You use the 'doc' function with the doc block's name inside double curly braces. For example, in a column description:

description: '{{ doc("customer_description") }}'

This inserts the reusable description.

beginner

Why are doc blocks helpful in dbt projects?

Doc blocks help keep documentation consistent, reduce repetition, and make it easier to update descriptions in one place instead of many, improving project maintainability.

intermediate

Can doc blocks include markdown formatting?

Yes, doc blocks support markdown formatting, so you can add lists, links, and emphasis to make your documentation clearer and more readable.

Where do you define doc blocks in a dbt project?

A In the profiles.yml file

B Inside SQL model files

C In the dbt_project.yml file

D In the .yml files under the 'docs:' key

Doc blocks are defined in .yml files under the 'docs:' key to keep documentation separate from SQL code.

How do you reference a doc block in a column description?

A Using {{ doc('block_name') }} inside the description

B Using {{ ref('block_name') }}

C Using {{ source('block_name') }}

D Using {{ config('block_name') }}

The correct way to reference a doc block is with {{ doc('block_name') }} inside the description field.

What is a main benefit of using doc blocks?

A They allow reusable documentation to keep descriptions consistent

B They replace the need for tests

C They automatically generate data models

D They speed up SQL query execution

Doc blocks help reuse documentation, making descriptions consistent and easier to maintain.

Can doc blocks contain markdown formatting?

A No, only plain text is allowed

B Yes, markdown formatting is supported

C Only HTML tags are allowed

D Only YAML syntax is allowed

Doc blocks support markdown, so you can add formatting like lists and links.

If you update a doc block description, what happens?

A You must manually update each model description

B Only the doc block file changes, no effect on models

C All references to that doc block update automatically

D The project will fail to compile

Updating a doc block updates all places where it is referenced, keeping documentation consistent.

Explain what a doc block is in dbt and how it helps with project documentation.

Think about writing a description once and using it many times.

Describe the steps to create and use a doc block for a column description in dbt.

Start with writing the reusable text, then call it where needed.

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