How to Document Columns in dbt: Syntax and Examples

In dbt, you document columns by adding a columns section inside your model's schema.yml file. Each column is described with a name and a description to explain its purpose, which helps generate clear documentation.

Syntax

To document columns in dbt, use a schema.yml file with a models section. Inside each model, add a columns list where each column has a name and a description. This tells dbt what each column means.

yaml

models:
  - name: your_model_name
    description: "Description of the model"
    columns:
      - name: column_1
        description: "Description of column_1"
      - name: column_2
        description: "Description of column_2"

Example

This example shows how to document two columns in a model called orders. It explains what each column means so anyone reading the docs understands the data.

yaml

models:
  - name: orders
    description: "This model contains order details."
    columns:
      - name: order_id
        description: "Unique identifier for each order."
      - name: order_date
        description: "Date when the order was placed."

Common Pitfalls

Common mistakes include:

• Not matching column names exactly with your model's columns.
• Forgetting to add descriptions, which makes docs less useful.
• Placing the columns section outside the model block.

Always double-check spelling and indentation in your schema.yml file.

yaml

models:
  - name: orders
    description: "Order details model"
    columns:
      - name: orderid  # Incorrect column name (should be order_id)
        description: "Unique order ID"

# Correct version:
models:
  - name: orders
    description: "Order details model"
    columns:
      - name: order_id
        description: "Unique order ID"

Quick Reference

Element	Description
models	Top-level list of models to document
name	The model's name matching your dbt model file
description	Text describing the model or column purpose
columns	List of columns to document inside the model
columns.name	Exact column name in the model
columns.description	Explanation of what the column means

Key Takeaways

Document columns in dbt by adding a columns section in your model's schema.yml file.

Each column needs a name matching the model and a clear description.

Keep indentation and spelling exact to avoid errors in documentation.

Descriptions help teammates understand your data better.

Use the quick reference table to remember the schema.yml structure.