documenting-dbt-models

dbt 文档

说明 WHY，而不只是 WHAT。包括粒度、业务规则和注意事项。

工作流

1. 研究现有文档模式

关键：添加新文档前，先遵循项目的文档风格。

# Find all schema.yml files with documentation
find . -name "schema.yml" | head -5

# Read well-documented models to learn patterns
cat models/marts/schema.yml | head -150
cat models/staging/schema.yml | head -150

从现有文档中提取以下信息：

• 描述长度（简短还是详细）
• 格式风格（纯文本还是带标题的 Markdown）
• 包含的信息（粒度？业务规则？注意事项？）
• 列描述的详细程度（所有列还是关键列）
• 是否使用 meta 标签或自定义属性

2. 阅读模型 SQL

cat models/<path>/<model_name>.sql

了解：转换、业务逻辑、联接、筛选条件。

3. 检查此模型的现有文档

# Find existing schema.yml
find . -name "schema.yml" -exec grep -l "<model_name>" {} \;

# Read existing docs
cat models/<path>/schema.yml | grep -A 100 "<model_name>"

4. 确定文档需求

对于每个模型，记录：

• 模型描述：用途、粒度、关键业务规则
• 列描述：业务含义，而不只是数据类型

对于每一列，请考虑：

• 它代表什么业务概念？
• 有什么注意事项或特殊值吗？
• 这些数据的来源是什么？

5. 编写文档

遵循第 1 步中发现的风格。格式示例（根据项目进行调整）：

version: 2

models:
  - name: orders
    description: |
      Order transactions at the order line item grain.
      Each row represents one product in one order.

      **Business Rules:**
      - Revenue recognized on ship_date, not order_date
      - Cancelled orders excluded (status != 'cancelled')
      - Returns processed as negative line items

      **Grain:** One row per order_id + product_id combination

    columns:
      - name: order_id
        description: |
          Unique identifier for the order.
          Source: orders.id from Stripe webhook

      - name: customer_id
        description: |
          Foreign key to customers table.
          NULL for guest checkouts (pre-2023 only)

      - name: revenue
        description: |
          Net revenue for this line item in USD.
          Calculation: unit_price * quantity - discount_amount
          Excludes tax and shipping

      - name: order_status
        description: |
          Current status of the order.
          Values: pending, processing, shipped, delivered, cancelled, returned

6. 生成文档

dbt docs generate
dbt docs serve  # Optional: preview locally

文档模式

注意：以下是默认模板。请始终根据项目现有风格进行调整。

模型描述模板

description: |
  [One sentence: what this model contains]

  **Grain:** [What does one row represent?]

  **Business Rules:**
  - [Key rule 1]
  - [Key rule 2]

  **Caveats:**
  - [Important limitation or edge case]

列描述模式

列类型	文档重点
主键	源系统、唯一性保证
外键	关联对象、NULL 处理方式
指标	计算公式、单位、排除项
日期	时区、代表的事件
状态/类别	所有可能的值、业务含义
布尔值/标记	true/false 在业务上的含义

记录计算字段

- name: gross_margin
  description: |
    Gross margin percentage.
    Calculation: (revenue - cogs) / revenue * 100
    NULL when revenue = 0 to avoid division by zero

反模式

• 未检查项目现有模式就添加文档
• 使用与现有文档不同的格式风格
• 只描述 WHAT（例如“订单 ID”），而不说明 WHY/上下文
• 缺少粒度说明
• 未说明 NULL 的处理方式
• 列缺少文档说明
• 直接复制列名作为描述