dbt sl 讓設定變成迴圈

dbt sl 讓你在本地把 parse、query、檢查 dimensions 串成一個可重複的驗證迴圈。

我用 dbt 一陣子後，最煩的不是 YAML 寫法，也不是命令記不住，而是那種「看起來都對，結果一跑就歪」的感覺。Semantic Layer 的文件一開始也有這味道：命令列得很整齊，流程也很像那麼回事，但我真正想要的是一個能在本地把錯誤抓出來的迴圈，不是再看一次漂亮的 setup checklist。因為老實說，metric 這種東西最怕的不是不能算，是算得很自信，然後在月報上把人帶進溝裡。

後來我才看懂，dbt 這份 Semantic Layer 設定文件 其實不是在教你「怎麼打開功能」，它是在教你一套開發節奏：先 parse，接著 query，再列 dimensions，最後回頭修。這種東西才有用。你不需要一篇看完就會的神文，你需要的是一個每次改完都能驗證的 loop。這篇我拆的就是這個 loop，順便把我覺得真正該抄走的版本整理出來。官方也明講，dbt CLI 的 dbt sl 子命令 是目前最完整的開發路徑，而 Studio IDE 比較像輕量替代。

dbt 先把你丟回終端機，這件事其實很合理

There are two options for developing a dbt project, including the Semantic Layer: dbt CLI — MetricFlow commands are embedded in the dbt CLI under the dbt sl subcommand. This is the easiest, most full-featured way to develop Semantic Layer code for the time being. Studio IDE — You can create semantic models and metrics in the Studio IDE.

白話講就是：dbt 不是要你先去點 UI，它是在告訴你，真正該信任的地方還是終端機。Studio IDE 可以用，但它不是主戰場。這點我反而認同，因為 Semantic Layer 這種東西如果還要靠滑鼠點來點去，我會很快失去耐心。我要的是能跑命令、看輸出、重跑、比對結果的地方，不是換個視窗裝飾一下。

我自己碰過最煩的情況，就是 metric 定義看起來很乾淨，結果每次改完都得在幾個介面間跳來跳去。那種 workflow 很像在整理桌面，不像在開發。CLI 的好處是它逼你把注意力放回 project 本身：檔案、命令、輸出、錯誤訊息，全都在同一條線上。這比「看起來方便」重要太多。

實操上我會這樣做：先把 Semantic Layer 的日常工作預設成 CLI，編輯器就用你最順手的那個，版本控制照常開著。Studio IDE 只拿來補你真的需要的地方，不要把它變成工作中心。你如果要先看官方命令面，直接開 dbt sl 命令參考。我通常會把它跟專案一起放在第二個螢幕，省得一直猜 subcommand。

• 日常開發先走 CLI，不要先想 UI。
• Studio IDE 當輔助工具，不當主流程。
• 命令參考固定開著，少靠記憶亂猜。

dbt parse 是最無聊、但最值錢的那一步

文件把 dbt parse 放進 Semantic Layer 的開發流程，這點我很買單。因為 parse 這件事看起來很普通，實際上是在幫你把專案轉成一個可被系統理解的 semantic manifest。不是只有語法檢查而已，是把你寫的東西變成 dbt 和 MetricFlow 能拿來推理的狀態。

翻譯一下就是：你以為你在改 YAML，實際上你是在改一個會影響查詢生成的世界模型。這差很多。很多人會在格式正確的時候就鬆一口氣，但格式正確不代表語意正確。join 能不能支援你想要的 dimension、time grain 對不對、metric 的形狀有沒有問題，這些都不是肉眼看 YAML 就能保證的。

我以前就踩過這種坑。檔案看起來沒錯，CI 也不一定立刻炸，但一到查詢階段就開始怪。那時候最浪費時間的不是修 bug，而是先花一堆時間證明「我真的不是寫錯字」。parse 的價值就在這裡，它先幫你把低級錯誤跟結構性問題擋掉，讓你不要拿著錯的前提去 debug 正確的地方。

實操上，我會把 dbt parse 變成每次改 semantic model 或 metric 之後的第一個動作。不要等到整個 session 結束才跑，因為那樣你只是在累積錯誤。parse 通過，只代表結構看起來合理；真正的正確性，還是要靠 query 去驗證。這兩件事不能混在一起，不然你會以為自己很穩，其實只是還沒撞牆。

如果你想理解這個中介狀態，官方把它叫做 semantic manifest。我會把它想成 YAML 和查詢引擎之間的契約。契約沒更新，後面所有測試都只是演戲。

dbt sl query 才是抓出「看起來合理但其實不對」的利器

文件對 dbt sl query 的描述很直接：它會對 semantic layer 執行查詢，回傳一小段結果。這句話我覺得很重要，因為它把 Semantic Layer 的開發從「寫定義」拉回到「看結果」。你不是在做靜態設定，你是在檢查這個定義跑起來之後到底會吐什麼數字。

dbt sl query will execute a query against your semantic layer and return a sample of the results. For example, if you're building a revenue model you can run dbt sl query --metrics revenue --group-by metric_time__month to validate that monthly revenue is calculating correctly.

白話就是：不要等 dashboard 幫你發現問題，直接在本地把 metric 拿出來問。特別是 revenue 這種大家都很在意的數字，你最好一開始就用你真正會交付的粒度去查，像月、週、或某個關鍵 dimension。只查總量很爽，但常常沒有用，因為總量對了不代表切開也對。

我自己遇過最煩的 bug，就是整體加總看起來正常，一加上時間維度就歪掉。那種錯誤很陰，因為它不會在第一眼就露餡。文件裡拿 --group-by metric_time__month 當例子，我覺得很對路。你應該測的是使用者真的會看的形狀，不是你最懶得查的形狀。

實操寫法很簡單：每次改 metric，都用你預期會被消費的 grain 去 query。使用者要看月報，你就查月；要看 region，你就把 region 加進去。結果不用大，夠你肉眼看就好。重點不是「查得過」，重點是「我敢不敢把這個數字拿出去」。

如果你要照官方命令面走，這份 dbt sl query 文件 值得常開。命令本身很短，但 workflow 的意思很大：semantic work 要立刻被質疑，不是先被欣賞。

• 用使用者真的會看的 grain 去查。
• 結果保持小而可讀，不要追求漂亮。
• 每次 semantic 改動後都重跑，不要只在最後驗一次。

列 dimensions 是防止我把能力吹過頭的方法

文件還提到 dbt sl list dimensions --metrics [metric name]。這看起來像小工具，但我覺得它其實是在逼你面對一件事：你到底有沒有真的把這個 metric 做到能被多角度切分。很多團隊最容易在這裡嘴硬，大家會先說「當然可以切」，然後才發現底層根本沒建好。

也就是說，list dimensions 的價值不是方便而已，它是在幫你對抗那種「我先答應再說」的開發習慣。Semantic Layer 很容易讓人誤以為只要定義了 metric，就自然有很多分析角度。但現實不是這樣。可用的 dimensions 就是可用的，沒有的就是沒有。

我很喜歡這個命令的一點，是它會強迫你做現況盤點。哪些 dimension 已經有了，哪些還缺，哪些是資料源本來就不支援，哪些只是你還沒加。這比空口說白話有用多了。你如果要跟 PM 或分析師講進度，拿這個結果比講感覺可靠。

實操上，我會把 dimension 列表當成 review checklist 的一部分。只要 metric 要進下一步，我就先看它到底支援哪些切法，然後對照實際的 business question。只要對不上，我不是補模型，就是收斂承諾。寧可說「還沒好」，也不要把一個看起來很彈性的 metric 丟出去，結果一切就破。

文件也提到你可以用 dbt sl list --help 看完整選項。我建議真的去看，因為 command family 通常都會把最有用的東西藏在下一層，不會老老實實放在範例裡讓你一次撿完。

semantic manifest 才是你真正要盯的中介產物

dbt 文件說 semantic manifest 會被上傳到 dbt，然後拿來在開發時執行 dbt sl 命令。這句話很關鍵，因為它把整個 workflow 的中心點講出來了：你不是只在編輯檔案，你是在產生一個系統可以理解、可以重用的狀態。

白話講就是，manifest 是人類可讀定義和機器可執行行為之間的橋。這座橋如果是舊的、髒的、沒更新的，你後面的 query 就會像在舊地圖上導航。你以為你在測最新改動，其實 runtime 看到的還是前一版。

我對這種中介產物一向很敏感，因為很多工具都會把「檔案已改」和「系統已知」這兩件事混在一起講。dbt 至少有把這個差異講清楚。文件裡提到 manifest 會提供 MetricFlow 一個 world state，讓它去生成查詢。這句我會直接畫線，因為它就是這套系統的核心邏輯。

實操上，我會把 parse 和 manifest 更新視為同一個動作的一部分。只要 semantic model 或 metric 有變，我就先假設目前的查詢結果不可信，直到我重新 parse、重新 query、重新確認。debug strange results 的第一步，不是急著改 metric，而是先確認 project state 是不是最新。

底層引擎如果你要往下看，官方也把你導到 MetricFlow。這是正確的方向，因為一旦你開始在意 join、dimension、time grain，光看範例就不夠了，你得知道引擎到底怎麼拼查詢。

Jaffle Shop 是訓練輪，但這種訓練輪很有必要

文件後面用的是 Jaffle Shop 這個虛構餐廳專案，我覺得這安排挺實際。很多人看到 toy example 會嫌簡化過頭，但我反而喜歡。因為你學 Semantic Layer 的時候，最不需要的就是一堆真實業務雜訊把流程蓋掉。你要先搞懂的是結構，不是公司內部命名哲學。

也就是說，像 food_revenue 這類範例 metric 的任務，不是模擬你的真實資料倉儲，而是讓你練習命令流：parse、query、list dimensions。這樣的好處是你可以先把工具行為和業務脈絡拆開，不會一開始就被 domain 細節拖死。

我自己在學新模型時也一樣，越小越好。只要有訂單、收入、時間、幾個維度，通常就夠看出問題了。你不需要一個超複雜的產線案例來證明自己很懂，你需要的是一個能讓你看出「這個 metric 到底怎麼動」的例子。學會之後，再把 pattern 套回自己的專案。

實操寫法就是：先拿最小可接受的例子練流程，跑通一次完整 loop，再回到真實專案。不要一開始就把整個 production model 拉進來，不然你會把理解工具的力氣，全拿去處理業務背景。那樣很累，而且沒必要。

• 先用 toy data 學命令流。
• 流程跑通後再搬到真實專案。
• 命名保持簡單，先看行為再看品牌。

可抄的模板

# dbt Semantic Layer 本地驗證 loop（我會直接抄這版）

## 1) 先 parse

dbt parse

## 2) 再用實際會用到的粒度查 metric

dbt sl query --metrics revenue --group-by metric_time__month

## 3) 列出這個 metric 真正支援的 dimensions

dbt sl list dimensions --metrics revenue

## 4) 每次改 semantic model / metric 都重跑一次

- 改完 semantic model 或 metric
- 立刻跑 `dbt parse`
- 用 `dbt sl query` 查你真的會交付的 grain
- 用 `dbt sl list dimensions --metrics [metric name]` 檢查可切分維度
- 如果結果跟 business question 對不上，先修模型，不要先修情緒

## 5) 我會固定開著的官方參考

- Semantic Layer 設定：https://docs.getdbt.com/best-practices/how-we-build-our-metrics/semantic-layer-2-setup
- dbt sl 命令總覽：https://docs.getdbt.com/reference/commands/sl
- dbt sl query：https://docs.getdbt.com/reference/commands/sl-query
- MetricFlow：https://docs.getdbt.com/reference/metricflow
- Jaffle Shop：https://github.com/dbt-labs/jaffle-shop

## 6) 我自己的判斷標準

- parse 過了，不代表 metric 對了
- query 過了，不代表所有 dimensions 都合理
- dimensions 對了，不代表業務問題都被回答了
- 只有當三者都對得起來，我才會說這個 semantic layer 版本可以往前走

這段模板真正值得抄的不是命令本身，是迴圈。先 parse，接著 query，再檢查 dimensions，然後回頭修。這就是 dbt 在這份文件裡真正想教你的事。我會把它當成自己的工作節奏，而不是一次性 setup。

來源我主要拆的是 dbt Developer Hub 這頁：Set up the dbt Semantic Layer。上面提到的命令與流程是原始文件的內容，我加進來的白話翻譯、工作方式整理跟模板，是我自己的整理版本。