Column descriptions in dbt - Step-by-Step Execution

Concept Flow - Column descriptions

Define model SQL

↓

Add column descriptions in schema.yml

↓

Run dbt docs generate

↓

View docs site

↓

See column descriptions in docs

This flow shows how to add descriptions to columns in dbt models and view them in generated documentation.

Execution Sample

dbt

models/my_model.sql:
select id, name, created_at from source_table

schema.yml:
models:
  - name: my_model
    columns:
      - name: id
        description: "Unique identifier"
      - name: name
        description: "Name of the entity"

This code defines a model selecting columns and adds descriptions for those columns in the schema.yml file.

Execution Table

Step	Action	File Affected	Result
1	Write SQL model selecting columns	models/my_model.sql	Model created with columns: id, name, created_at
2	Add column descriptions in schema.yml	models/schema.yml	Descriptions added for id and name columns
3	Run 'dbt docs generate'	Command line	Documentation site generated with column descriptions
4	Open docs site in browser	Browser	Column descriptions visible under my_model columns
5	Check column without description	Docs site	created_at shows no description (empty)

💡 All columns with descriptions appear in docs; columns without descriptions show empty.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
model_columns	[]	[id, name, created_at]	[id, name, created_at]	[id, name, created_at]
column_descriptions	{}	{"id": "Unique identifier", "name": "Name of the entity"}	{"id": "Unique identifier", "name": "Name of the entity"}	{"id": "Unique identifier", "name": "Name of the entity"}
docs_generated	False	False	True	True

Key Moments - 2 Insights

Why does the created_at column show no description in the docs?

Because in the schema.yml file, only id and name columns have descriptions. created_at was not given a description, so it appears empty in the docs (see execution_table step 5).

Do column descriptions affect the SQL model output?

No, descriptions only add metadata for documentation. The SQL model output remains the same (see execution_table step 1 and 2).

Visual Quiz - 3 Questions

Look at the execution table, at which step are column descriptions added?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Check the 'Action' column in execution_table rows for when descriptions are added.

According to variable_tracker, what is the value of docs_generated after step 3?

A False

B Undefined

C True

D Null

💡 Hint

Look at the docs_generated row in variable_tracker after step 3.

If you add a description for created_at in schema.yml, what changes in the docs?

A created_at column will show its description

B No change, descriptions are ignored

C Model SQL will change

D Docs site will fail to generate

💡 Hint

Refer to key_moments about columns without descriptions and their effect on docs.

Concept Snapshot

dbt Column Descriptions:
- Add descriptions in schema.yml under models > columns
- Descriptions do not affect SQL output
- Run 'dbt docs generate' to build docs
- View descriptions in docs site
- Columns without descriptions show empty

Full Transcript

In dbt, you write SQL models selecting columns. To add descriptions for these columns, you edit the schema.yml file and list each column with a description. Running 'dbt docs generate' creates a documentation site where these descriptions appear. Columns without descriptions show no text in docs. Descriptions help explain columns but do not change the SQL output. This process helps teams understand data better by reading docs.

Practice

1. What is the main purpose of adding column descriptions in dbt?

easy

A. To change the data type of columns

B. To create new columns in the model

C. To explain what each column means for better understanding

D. To write SQL queries inside the YAML file

Solution

1. Step 1: Understand the role of column descriptions

   Column descriptions provide explanations about what each column represents in the data model.

2. Step 2: Differentiate from other YAML uses

   They do not change data types, create columns, or contain SQL code; they only describe columns.

3. Final Answer:

   To explain what each column means for better understanding -> Option C

4. Quick Check:

   Column descriptions = explain columns [OK]

Hint: Descriptions explain columns, not change data or structure [OK]

Common Mistakes:

• Thinking descriptions change data types
• Confusing descriptions with SQL code
• Assuming descriptions create new columns

2. Which of the following is the correct syntax to add a column description in a dbt YAML file?

easy

A. description:
customer_id: 'Unique ID for each customer'

B. columns:
- name: customer_id
description: 'Unique ID for each customer'

C. columns:
customer_id: 'Unique ID for each customer'

D. columns:
- customer_id: 'Unique ID for each customer'

Solution

1. Step 1: Recall YAML structure for columns in dbt

   The correct format uses a list under columns: with each item having name and description keys.

2. Step 2: Compare options to correct format

   columns: - name: customer_id description: 'Unique ID for each customer' matches the correct YAML syntax with dash, name, and description keys properly indented.

3. Final Answer:

   columns: - name: customer_id description: 'Unique ID for each customer' -> Option B

4. Quick Check:

   YAML columns list with name and description = columns: - name: customer_id description: 'Unique ID for each customer' [OK]

Hint: Use dash list with name and description keys in YAML [OK]

Common Mistakes:

• Using key-value pairs without dash list
• Putting description outside columns section
• Incorrect indentation or missing name key

3. Given this YAML snippet in a dbt model:

columns:
  - name: order_id
    description: 'Unique order identifier'
  - name: order_date
    description: 'Date when order was placed'

What will dbt show for the order_date column in documentation?

medium

A. No description available

B. Unique order identifier

C. order_date

D. Date when order was placed

Solution

1. Step 1: Locate the description for order_date

   The YAML shows order_date has description 'Date when order was placed'.

2. Step 2: Understand dbt documentation behavior

   dbt uses the description text to show in docs, not the column name or other text.

3. Final Answer:

   Date when order was placed -> Option D

4. Quick Check:

   dbt docs show column description text [OK]

Hint: dbt docs show the description text, not column name [OK]

Common Mistakes:

• Confusing column name with description
• Assuming no description if present
• Picking wrong description text

4. You wrote this YAML for column descriptions but dbt docs shows no descriptions:

columns:
  - name: user_id
    description 'User unique ID'

What is the error causing descriptions not to appear?

medium

A. Missing colon after description key

B. Wrong indentation of columns

C. Missing dash before name

D. Description text should be uppercase

Solution

1. Step 1: Check YAML syntax for description key

   The line description 'User unique ID' is missing a colon after description.

2. Step 2: Understand YAML parsing impact

   Without the colon, YAML is invalid and dbt cannot read the description, so docs show no description.

3. Final Answer:

   Missing colon after description key -> Option A

4. Quick Check:

   YAML keys need colon after them [OK]

Hint: Always put colon after YAML keys like description [OK]

Common Mistakes:

• Forgetting colon after keys
• Incorrect indentation
• Assuming case sensitivity matters

5. You want to add descriptions for multiple columns in a dbt model YAML file. Which approach correctly documents two columns product_id and price with descriptions, ensuring dbt docs will display them properly?

hard

A. columns:
- name: product_id
description: 'ID of the product'
- name: price
description: 'Price in USD'

B. columns:
product_id: 'ID of the product'
price: 'Price in USD'

C. columns:
- product_id: 'ID of the product'
- price: 'Price in USD'

D. columns:
name: product_id
description: 'ID of the product'
name: price
description: 'Price in USD'

Solution

1. Step 1: Recall correct YAML list format for multiple columns

   Each column must be an item in a list with name and description keys.

2. Step 2: Evaluate each option's structure

   columns: - name: product_id description: 'ID of the product' - name: price description: 'Price in USD' correctly uses a list with two items, each having name and description properly indented.

3. Final Answer:

   columns: - name: product_id description: 'ID of the product' - name: price description: 'Price in USD' -> Option A

4. Quick Check:

   List of columns with name and description keys = columns: - name: product_id description: 'ID of the product' - name: price description: 'Price in USD' [OK]

Hint: Use dash list with name and description for each column [OK]

Common Mistakes:

• Using key-value pairs without dash list
• Repeating keys without list items
• Incorrect indentation breaking YAML