Why documentation makes data discoverable in dbt

Introduction

Documentation helps people find and understand data easily. It explains what data means and how to use it.

When you want your team to quickly find the right data for reports.

When new team members need to learn about data sources fast.

When you want to avoid confusion about data definitions.

When you want to keep track of changes in data over time.

When you want to share data knowledge across different departments.

Syntax

dbt

models:
  - name: model_name
    description: "A clear explanation of the data model"
    columns:
      - name: column_name
        description: "What this column means and how to use it"

Documentation is written in YAML format in files like schema.yml.

Descriptions help users understand the purpose of tables and columns.

Examples

This example documents a model named 'customers' and its column 'customer_id'.

dbt

version: 2
models:
  - name: customers
    description: "Contains customer information like name and email"
    columns:
      - name: customer_id
        description: "Unique ID for each customer"

This documents the 'orders' model and explains the 'order_date' column.

dbt

version: 2
models:
  - name: orders
    description: "Details of customer orders"
    columns:
      - name: order_date
        description: "Date when the order was placed"

Sample Program

This sample shows how to document a 'sales' model with descriptions for the model and its columns.

dbt

version: 2
models:
  - name: sales
    description: "Sales data including product and revenue"
    columns:
      - name: product_id
        description: "ID of the product sold"
      - name: revenue
        description: "Revenue generated from the sale"

# This YAML file helps dbt generate documentation that makes sales data easy to find and understand.

Important Notes

Good documentation saves time by reducing questions about data meaning.

Keep descriptions clear and simple for everyone to understand.

Update documentation whenever data models change to keep it accurate.

Summary

Documentation explains data so people can find and use it easily.

It is written in YAML inside dbt model files.

Clear descriptions help everyone understand data purpose and usage.