Documenting models in YAML in dbt

Introduction

Documenting models in YAML helps explain what your data models do. It makes your work clear for others and yourself later.

When you want to describe the purpose of a data model in your project.

When you need to add descriptions for columns in your tables.

When you want to keep your data project organized and easy to understand.

When sharing your project with teammates who need to know what each model does.

When preparing documentation for data audits or reviews.

Syntax

dbt

version: 2
models:
  - name: model_name
    description: 'Description of the model'
    columns:
      - name: column_name
        description: 'Description of the column'

The YAML file usually starts with version: 2 to specify the schema version.

Indentation is important in YAML. Use 2 spaces per level for clarity.

Examples

This example documents a customers model with two columns described.

dbt

version: 2
models:
  - name: customers
    description: 'Contains customer details'
    columns:
      - name: customer_id
        description: 'Unique ID for each customer'
      - name: email
        description: 'Customer email address'

This example shows documentation for a sales model with sale ID and amount columns.

dbt

version: 2
models:
  - name: sales
    description: 'Sales transactions data'
    columns:
      - name: sale_id
        description: 'Unique sale identifier'
      - name: amount
        description: 'Sale amount in USD'

Sample Program

This YAML documents an orders model with three columns and their descriptions.

dbt

version: 2
models:
  - name: orders
    description: 'Table containing order information'
    columns:
      - name: order_id
        description: 'Unique identifier for each order'
      - name: order_date
        description: 'Date when the order was placed'
      - name: customer_id
        description: 'ID of the customer who placed the order'

Important Notes

Always keep your YAML files well-indented to avoid errors.

Descriptions help others understand your data without reading code.

You can add tests and tags in the same YAML file for more features.

Summary

Documenting models in YAML makes your data project clear and easy to use.

Use models and columns sections to add descriptions.

Good documentation helps teamwork and future maintenance.