Documenting models in YAML in dbt - Mini Project: Build & Apply

Documenting models in YAML

📖 Scenario: You are working on a data project using dbt. You have created some models (tables) and now want to add clear documentation for each model and its columns. This helps your team understand what each model and column means.

🎯 Goal: Learn how to write YAML files to document dbt models and their columns with descriptions.

📋 What You'll Learn

Create a YAML file with model documentation

Add model name and description

Add column names and descriptions

Use correct YAML syntax for dbt documentation

💡 Why This Matters

🌍 Real World

Documenting data models clearly helps teams understand data sources and improves collaboration.

💼 Career

Data analysts and engineers often write YAML documentation for dbt models to maintain data quality and clarity.

1

Create a YAML file with a model entry

Create a YAML file with a models key. Under it, add a model with the name orders and a description 'This model contains order data.'

dbt

# Your code here

Need a hint?

Start with models: then add a list item with - name: orders and description:

2

Add columns section with one column

Under the orders model, add a columns key. Add one column with the name order_id and description 'Unique identifier for each order.'

dbt

models:
  - name: orders
    description: 'This model contains order data.'
    # Your code here

Need a hint?

Indent columns: under the model, then add a list item with - name: order_id and description:

3

Add a second column with description

Add another column under columns with the name order_date and description 'Date when the order was placed.'

dbt

models:
  - name: orders
    description: 'This model contains order data.'
    columns:
      - name: order_id
        description: 'Unique identifier for each order.'
      # Your code here

Need a hint?

Add another list item under columns: with the new column name and description.

4

Print the full YAML content

Print the full YAML content stored in a variable called yaml_doc. Assign the entire YAML text to yaml_doc as a multi-line string, then print it.

dbt

# Assign the YAML content to yaml_doc and print it
# Your code here

Need a hint?

Use triple quotes to assign the YAML text to yaml_doc and then print it.