Documenting models in YAML in dbt - Step-by-Step Execution

Concept Flow - Documenting models in YAML

Create YAML file

↓

Define model metadata

↓

Add descriptions and columns

↓

Save and run dbt docs generate

↓

View documentation in browser

This flow shows how to write model documentation in YAML, generate docs, and view them.

Execution Sample

dbt

version: 2
models:
  - name: customers
    description: "Customer details table"
    columns:
      - name: id
        description: "Unique customer ID"

This YAML snippet documents a model named 'customers' with a description and column info.

Execution Table

Step	Action	YAML Content	dbt Command	Result
1	Create YAML file	Empty file named schema.yml	N/A	File created
2	Add model metadata	version: 2 models: - name: customers description: "Customer details table" columns: - name: id description: "Unique customer ID"	N/A	YAML content added
3	Save file	schema.yml saved	N/A	File saved
4	Run dbt docs generate	N/A	dbt docs generate	Documentation site generated
5	Open docs site	N/A	dbt docs serve	Documentation visible in browser
6	Exit	N/A	N/A	Process complete

💡 Documentation generated and served successfully

Variable Tracker

Variable	Start	After Step 2	After Step 4	Final
schema.yml content	empty	model and columns defined	unchanged	unchanged
dbt docs site	not generated	not generated	generated	served and visible

Key Moments - 3 Insights

Why do we need to add descriptions under 'columns' in the YAML?

Descriptions under 'columns' explain each field in the model, making docs clearer. See execution_table step 2 where columns are defined.

What happens if we forget to run 'dbt docs generate' after editing YAML?

The documentation site won't update with new info. Step 4 in execution_table shows this command is needed to generate docs.

Can we document multiple models in one YAML file?

Yes, you list multiple models under 'models:' in the YAML. This is implied in step 2 where model metadata is added.

Visual Quiz - 3 Questions

Look at the execution_table, what is the YAML content after step 2?

A Documentation site generated

B Empty file

C Model name and description with columns

D File saved but empty

💡 Hint

Check the 'YAML Content' column in execution_table row for step 2

At which step does the documentation site become visible in the browser?

A Step 5

B Step 3

C Step 4

D Step 6

💡 Hint

Look at the 'Result' column in execution_table for step 5

If you add a new column description but skip 'dbt docs generate', what happens?

A New description appears immediately

B Documentation site does not show new description

C Documentation site updates automatically

D YAML file is deleted

💡 Hint

Refer to key_moments about the importance of running 'dbt docs generate'

Concept Snapshot

Document models in YAML with:
version: 2
models:
  - name: model_name
    description: "Model description"
    columns:
      - name: column_name
        description: "Column description"
Run 'dbt docs generate' to build docs, then 'dbt docs serve' to view.

Full Transcript

This visual execution shows how to document dbt models using YAML files. First, create a YAML file named schema.yml. Then add model metadata including the model name, description, and columns with their descriptions. Save the file. Next, run the command 'dbt docs generate' to build the documentation site. Finally, run 'dbt docs serve' to open the docs in a browser. The variable tracker shows the YAML content changes and when the docs site is generated. Key moments clarify why column descriptions matter and why running 'dbt docs generate' is necessary. The quiz tests understanding of YAML content at each step and the documentation generation process.

Practice

1. What is the main purpose of documenting models in YAML in a dbt project?

easy

A. To write SQL queries inside YAML files

B. To execute dbt models automatically

C. To add clear descriptions for models and columns to improve understanding

D. To store raw data files

Solution

1. Step 1: Understand the role of YAML documentation

   YAML files in dbt are used to add metadata like descriptions, not to run code or store data.

2. Step 2: Identify the benefit of documentation

   Adding descriptions for models and columns helps team members understand the data and maintain the project easily.

3. Final Answer:

   To add clear descriptions for models and columns to improve understanding -> Option C

4. Quick Check:

   Documentation purpose = Add descriptions [OK]

Hint: Documentation in YAML means adding descriptions, not code [OK]

Common Mistakes:

• Thinking YAML runs SQL code
• Confusing YAML with data storage
• Ignoring the importance of descriptions

2. Which of the following is the correct way to start documenting a model named orders in a YAML file?

easy

A. models:
orders
description: 'Contains order details'

B. model:
name: orders
description: 'Contains order details'

C. models:
- orders:
description: 'Contains order details'

D. models:
- name: orders
description: 'Contains order details'

Solution

1. Step 1: Recall YAML syntax for dbt model documentation

   dbt expects a list under models: with each model as a dictionary containing name and description.

2. Step 2: Match the correct structure

   models: - name: orders description: 'Contains order details' correctly uses a list with a dictionary having name and description. Other options misuse keys or structure.

3. Final Answer:

   models: - name: orders description: 'Contains order details' -> Option D

4. Quick Check:

   Model list with name and description = models: - name: orders description: 'Contains order details' [OK]

Hint: Use dash (-) for list items under models in YAML [OK]

Common Mistakes:

• Using singular 'model' instead of 'models'
• Not using dash for list items
• Incorrect indentation or key names

3. Given this YAML snippet documenting a model and its columns:

models:
  - name: customers
    description: 'Customer information'
    columns:
      - name: id
        description: 'Unique customer ID'
      - name: email
        description: 'Customer email address'

What will dbt show as the description for the email column?

medium

A. Unique customer ID

B. Customer email address

C. Customer information

D. No description

Solution

1. Step 1: Locate the column description in YAML

   The email column is listed under columns with its own description key.

2. Step 2: Identify the description text for the email column

   The description for email is 'Customer email address', which dbt will display for that column.

3. Final Answer:

   Customer email address -> Option B

4. Quick Check:

   Column description matches YAML text [OK]

Hint: Column descriptions are under columns > name in YAML [OK]

Common Mistakes:

• Confusing model description with column description
• Missing indentation causing YAML parsing errors
• Assuming no description if not repeated

4. You wrote this YAML to document a model but dbt throws an error:

models:
  - name: sales
    description: 'Sales data'
    columns:
      name: amount
      description: 'Sale amount'

What is the error in this YAML?

medium

A. Missing dash (-) before column name and description

B. Incorrect model name key

C. Description should be under models, not columns

D. YAML does not support nested lists

Solution

1. Step 1: Check YAML list syntax for columns

   Each column should be a list item with a dash (-) before its dictionary of keys.

2. Step 2: Identify missing dash in columns

   The name and description keys under columns lack the dash, so YAML treats them as keys of columns instead of list items.

3. Final Answer:

   Missing dash (-) before column name and description -> Option A

4. Quick Check:

   List items need dash (-) in YAML [OK]

Hint: Use dash (-) before each column in columns list [OK]

Common Mistakes:

• Forgetting dash for list items
• Misplacing description keys
• Confusing YAML lists and dictionaries

5. You want to document two models, users and transactions, each with columns and descriptions. Which YAML structure correctly documents both models with their columns?

hard

A. models:
- name: users
description: 'User data'
columns:
- name: user_id
description: 'User identifier'
- name: transactions
description: 'Transaction data'
columns:
- name: transaction_id
description: 'Transaction identifier'

B. models:
users:
description: 'User data'
columns:
user_id: 'User identifier'
transactions:
description: 'Transaction data'
columns:
transaction_id: 'Transaction identifier'

C. models:
- users:
description: 'User data'
columns:
- user_id: 'User identifier'
- transactions:
description: 'Transaction data'
columns:
- transaction_id: 'Transaction identifier'

D. models:
name: users
description: 'User data'
columns:
- name: user_id
description: 'User identifier'
name: transactions
description: 'Transaction data'
columns:
- name: transaction_id
description: 'Transaction identifier'

Solution

1. Step 1: Understand YAML list structure for multiple models

   dbt expects models as a list of dictionaries, each with name, description, and columns as a list.

2. Step 2: Evaluate each option's structure

   models: - name: users description: 'User data' columns: - name: user_id description: 'User identifier' - name: transactions description: 'Transaction data' columns: - name: transaction_id description: 'Transaction identifier' correctly uses a list with two model dictionaries, each with proper keys and column lists. The other options misuse keys or structure. models: name: users description: 'User data' columns: - name: user_id description: 'User identifier' name: transactions description: 'Transaction data' columns: - name: transaction_id description: 'Transaction identifier' repeats keys incorrectly.

3. Final Answer:

   models: - name: users description: 'User data' columns: - name: user_id description: 'User identifier' - name: transactions description: 'Transaction data' columns: - name: transaction_id description: 'Transaction identifier' -> Option A

4. Quick Check:

   Multiple models as list items with name and columns = models: - name: users description: 'User data' columns: - name: user_id description: 'User identifier' - name: transactions description: 'Transaction data' columns: - name: transaction_id description: 'Transaction identifier' [OK]

Hint: List each model with dash (-) and include columns as lists [OK]

Common Mistakes:

• Using model names as keys instead of list items
• Repeating keys at same level
• Not using dash for multiple models