How to Use Description in Schema YML in dbt

In dbt, you add a description field inside your schema YAML file under models, columns, or tests to document them. This helps generate clear documentation and improves understanding of your data assets.

Syntax

The description field is used inside the schema.yml file under different sections like models, columns, or tests. It is a simple key-value pair where the key is description and the value is a string explaining the item.

Example parts:

• models: Describes the whole model/table.
• columns: Describes individual columns inside a model.
• tests: Describes tests applied to models or columns.

yaml

models:
  - name: my_model
    description: "This model contains sales data aggregated by month."
    columns:
      - name: sales_date
        description: "The date of the sale in YYYY-MM-DD format."
      - name: total_sales
        description: "Total sales amount in USD for the given date."

Example

This example shows how to add descriptions to a model and its columns in a schema.yml file. These descriptions will appear in dbt documentation when you run dbt docs generate.

yaml

version: 2

models:
  - name: orders
    description: "This model contains all customer orders with details."
    columns:
      - name: order_id
        description: "Unique identifier for each order."
      - name: customer_id
        description: "Identifier for the customer who placed the order."
      - name: order_date
        description: "Date when the order was placed."
      - name: total_amount
        description: "Total amount of the order in USD."

Common Pitfalls

Common mistakes when using description in dbt schema files include:

• Not indenting properly in YAML, which breaks the file.
• Missing the version: 2 declaration at the top of the schema file.
• Using descriptions outside the allowed sections like models or columns.
• Forgetting to run dbt docs generate and dbt docs serve to see the descriptions in the documentation.

Example of wrong indentation and fix:

yaml

# Wrong indentation example
models:
- name: my_model
  description: "Missing proper indentation"
  columns:
    - name: col1
      description: "Proper indentation needed"

# Correct indentation example
models:
  - name: my_model
    description: "Proper indentation here"
    columns:
      - name: col1
        description: "Proper indentation here"

Quick Reference

Section	Purpose	Example usage
models	Describe the whole model/table	description: "This model contains sales data."
columns	Describe individual columns	description: "Date of sale in YYYY-MM-DD."
tests	Describe tests on models or columns	description: "Checks for null values."

Key Takeaways

Add description fields in your schema.yml under models and columns to document your data.

Always start your schema file with version: 2 to use descriptions.

Indent YAML properly to avoid syntax errors.

Run dbt docs generate and dbt docs serve to view descriptions in documentation.

Descriptions improve clarity and maintainability of your dbt project.