dbt Docs 自動化產生文件

資料團隊常面臨一個痛點：文件永遠跟不上程式碼的變更。今天更新了邏輯，但 Wiki 或 Excel 的文件卻忘了改，導致使用者看著過時的文件用錯資料。

dbt 的解決方案是：文件即程式碼 (Docs as Code)。

dbt 會直接讀取你的程式碼與 YAML 設定，自動生成一個精美的靜態網站，包含：

  • 資料字典 (Data Dictionary)：Table 與 Column 的描述、型別。
  • 血緣關係圖 (Data Lineage)：視覺化呈現資料從 Source 到 Mart 的流向。
  • 原本的 SQL 碼：查看編譯前與編譯後的 SQL。

因為是直接從程式碼生成的，所以保證文件與程式碼永遠同步。

撰寫文件

最簡單的方式，就是直接在 Model 的 Properties YAML 檔 (通常命名為 schema.yml 或 models.yml) 中加入 description 屬性。

version: 2

models:
  - name: customers
    description: '客戶維度表，包含基本資料與狀態。'
    columns:
      - name: id
        description: '客戶的唯一識別碼 (Primary Key)'
        tests:
          - unique
          - not_null

使用 Doc Blocks (長篇描述)

如果你想幫一個複雜的欄位寫超過三行的解釋，YAML 的格式會變得很難閱讀。dbt 提供了 docs 區塊 (Documentation Blocks) 的功能，讓你把詳細的文字說明寫在 .md (Markdown) 檔裡，然後在 .yml 檔中引用它。

如何操作？

第一步：建立 .md 檔案

在 models/ (或 macros/) 下建立一個 Markdown 檔案，例如 models/docs.md：

{% docs table_customers %}
這是一張**客戶維度表**。

包含以下資訊：

- 客戶基本資料
- 會員等級
- 註冊時間

注意：已刪除的客戶也會保留在此表中，請過濾 status = 'deleted'。
{% enddocs %}
Markdown 的「檔名」本身不重要，但你在檔案內定義的 docs 區塊名稱必須是唯一的。

第二步：在 .yml 中引用

models:
  - name: customers
    description: '{{ doc("table_customers") }}'

檔案放置的位置

就像 .yml 檔一樣，dbt 會自動搜尋 dbt_project.yml 中 model-paths 指定路徑下的所有 .md 檔案。

通常建議的結構是：

  • models/staging/stg_xxx.yml (定義結構與測試)
  • models/staging/stg_xxx.md (定義長篇說明)

產生與檢視文檔

要產生文件網站，請執行：

dbt docs generate

這個指令會讀取專案資訊並在 target/ 目錄下產生 manifest.json 和 catalog.json。

接著，啟動本地伺服器來預覽：

dbt docs serve

執行後，瀏覽器會自動打開 http://localhost:8080。

探索文檔網站

在 dbt Docs 網站中，你可以：

  1. 搜尋：左上角搜尋框可以快速找到任何 table 或 column。
  2. 查看 Lineage Graph：點擊右下角的綠色按鈕 (View Lineage Graph)，可以看到該 model 的上下游關係圖。這對於理解複雜的資料流非常有幫助。
  3. 檢視程式碼：點擊 "Source" 或 "Compiled" 標籤，查看原始碼。

專案首頁 (Overview)

你可以自訂文件網站的首頁內容。只要在專案目錄下建立一個 analysis/overview.md (或任何 .md 檔)，並定義 __overview__ doc block：

{% docs __overview__ %}

# 歡迎來到 My Company Data Warehouse

這份文件由 dbt 自動產生...

## 聯絡我們

有問題請洽 Data Team
{% enddocs %}

總結

dbt Docs 是一個殺手級的功能，它大大降低了維護文件的成本，並提升了資料的透明度。養成在開發 model 時順手寫上 description 的好習慣，你的隊友與未來的自己會感謝你的。