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:<br>

docs:<br>  customer_description:<br>    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:<br>

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.