CLI 查詢：grep + jq

JSONL 格式的最大優勢是原生支援 Unix 文字處理工具。不需要額外的查詢語言、不需要客戶端工具、不需要連線到 database。

常見查詢模式

按事件類型過濾：

1grep '"type":"error"' events-2026-06-19.jsonl | jq .

按 namespace 過濾：

1grep '"name":"terminal.connect' events-2026-06-19.jsonl | jq .

按時間範圍過濾（跨檔案）：

1cat events-2026-06-1{8,9}.jsonl | jq 'select(.ts >= "2026-06-18T18:00:00")'

統計每種事件的數量：

1jq -r '.name' events-2026-06-19.jsonl | sort | uniq -c | sort -rn

grep 友好的 JSONL 設計

JSONL 的每行 JSON 結構影響 grep 的查詢效率和準確性。

把常用過濾欄位放在 JSON 的前面。grep 是字串匹配，把 type 和 name 放在行首讓 grep pattern 更簡單、誤匹配更少。

避免 JSON 值中包含雙引號。事件名稱和型別用簡單字串（不含特殊字元），讓 grep 的 pattern 不需要處理 escape。

每行 JSON 不換行。JSONL 的定義就是每行一個 JSON，但格式化工具可能自動加換行。寫入時用 json.Marshal（Go）或 JSON.stringify（JS）確保單行輸出。

HTTP 查詢 endpoint

HTTP 查詢 endpoint 讓非 CLI 使用者（dashboard、自動化腳本、其他服務）能查詢事件資料。

Endpoint 設計

1GET /v1/events?type=error&name=terminal.connect.*&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&limit=100

查詢參數：

回應格式

 1{
 2  "events": [
 3    {
 4      "v": 1,
 5      "type": "error",
 6      "timestamp": "2026-06-19T08:42:00Z",
 7      "source": { "sdk": "python", "platform": "macos", "app": "claude-hooks" },
 8      "name": "hook.failure",
 9      "level": "error",
10      "data": { "hook": "branch-status-reminder", "step": "validation" },
11      "error": { "message": "KeyError: 'status'", "stack": "Traceback...", "type": "KeyError" },
12      "context": { "session_id": "sess-abc-123" }
13    }
14  ],
15  "total": 42,
16  "limit": 100,
17  "offset": 0
18}

events 陣列按 timestamp 降序排列。total 是符合篩選條件的全量筆數（不受 limit 截斷），讓呼叫端計算分頁（total_pages = ceil(total / limit)）。分頁用 offset-based（offset=100 取第二頁），適合資料量在十萬筆以下的場景。資料量大到 offset 效能不足時，改用 cursor-based（after=<last_event_id>），但 cursor-based 是 PostgreSQL 層的演進，SQLite 層用 offset 足夠。

實作策略

HTTP 查詢 endpoint 的底層實作可以直接讀取 JSONL 檔案 — 根據 from/to 確定要讀哪些日期的檔案，逐行 parse 並過濾。這個實作在資料量小（單日萬筆以下）時足夠快。

當查詢效能成為問題時，在 JSONL 之上加一層索引（按 type/name 建立反向索引），或演進到 SQLite 儲存（見 規模演進）。

聚合查詢

逐筆查詢回答「發生了什麼」，聚合查詢回答「發生了多少」。Error 調查的第一步是定位最頻繁的 error — 「哪些 error 最多」需要按 name 分群計數的聚合結果，逐筆列表在這個階段資訊量太大。

Endpoint 設計

1GET /v1/events/summary?type=error&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&group_by=name

回傳按 name 分群的統計：

1{
2  "groups": [
3    { "name": "hook.failure", "count": 15, "last_seen": "2026-06-19T08:42:00Z" },
4    { "name": "terminal.connect.failed", "count": 3, "last_seen": "2026-06-19T07:10:00Z" }
5  ],
6  "total": 18,
7  "from": "2026-06-18T00:00:00Z",
8  "to": "2026-06-19T00:00:00Z"
9}

查詢參數和逐筆查詢共用（type、name、from、to），額外的 group_by 指定分群欄位（name 或 type）。

SQL 實作

SQLite backend 下直接用 GROUP BY：

1SELECT name, COUNT(*) as count, MAX(timestamp) as last_seen
2FROM events
3WHERE type = 'error' AND timestamp BETWEEN ? AND ?
4GROUP BY name
5ORDER BY count DESC
6LIMIT 100

有 type + timestamp 複合索引時，這個查詢在 10 萬筆資料內的效能和逐筆查詢相當 — GROUP BY 在索引掃描後做，不需要全表掃描。

和逐筆查詢的定位差異

兩者是互補的工作流 — 聚合查詢定位問題方向，逐筆查詢深入細節。Dashboard 的 Error 列表頁面直接消費聚合查詢的結果。

CLI vs HTTP 的定位

兩種介面共存 — CLI 用於開發者日常 debug，HTTP endpoint 用於自動化和遠端存取。兩者底層讀取同一份 JSONL 檔案，結果一致。

下一步路由

• JSONL 儲存的設計 → JSONL 儲存設計
• Rule engine 的自動化處理 → Rule engine 設計
• Collector 的完整架構 → Collector 架構

五種查詢場景各自需要不同的事件類型、欄位和查詢模式。每種場景的查詢模式也決定了需要 SQLite 層還是 PostgreSQL 層（見 功能分層與 Backend 選擇）。

Debug 查詢

Debug 查詢回答「問題出在哪」。觸發時機是使用者回報問題或 error alert 觸發後，開發者需要還原問題的 context。

查詢場景

剛才使用者回報的問題

查詢模式：用 session_id 過濾，拉出該 session 的全部事件，按時間排序。

1-- SQLite
2SELECT type, name, ts, data
3FROM events
4WHERE session_id = 'abc-123'
5ORDER BY ts;

需要的事件欄位：session_id（關聯同次使用的事件）、ts（排序）、error 的 stack trace 和 step（定位失敗點）。

這個 error 多常發生

查詢模式：按 error name 分群計數，看時間趨勢。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       strftime('%Y-%m-%d', ts) as day
4FROM events
5WHERE type = 'error'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY name, day
8ORDER BY day, count DESC;

需要的事件欄位：type=‘error’、name（分群鍵）、ts（時間分桶）。

需要的事件

Alerting 查詢

Alerting 查詢回答「需要注意嗎」。分兩種機制：rule engine 的即時評估（事件到達時逐筆比對規則）和事後查詢的趨勢分析。

查詢場景

Error 數量突然上升

查詢模式：最近 1 小時的 error 計數 vs 前一天同時段，偏差超過閾值則告警。

1-- SQLite
2SELECT COUNT(*) as recent_count
3FROM events
4WHERE type = 'error'
5  AND ts >= datetime('now', '-1 hour');

Rule engine 的即時版：每收到一筆 error 事件，遞增計數器，計數器超過閾值觸發動作。

特定 error 首次出現

查詢模式：收到 error 時查是否有歷史記錄。

1-- SQLite
2SELECT COUNT(*) FROM events
3WHERE type = 'error' AND name = ?
4  AND ts < ?;

結果為 0 代表首次出現 — 觸發「新 error 類型」告警。Sentry 的核心功能之一就是這個查詢。

Rule engine vs 事後查詢

Rule engine 逐筆評估，延遲在毫秒級，適合「error 出現就通知」。事後查詢用 SQL 聚合，延遲在秒到分鐘級，適合「過去一小時的 error 趨勢」。兩者互補 — rule engine 做即時告警、SQL 查詢做事後分析。

需要的事件

產品決策查詢

產品決策查詢回答「使用者怎麼用產品」。從簡單的功能使用率到複雜的 funnel 分析。

查詢場景

新功能有多少人用

查詢模式：按 event name 計數。SQLite 層即可。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       COUNT(DISTINCT session_id) as unique_sessions
4FROM events
5WHERE type = 'event'
6  AND name LIKE 'new_feature.%'
7  AND ts >= datetime('now', '-7 days')
8GROUP BY name;

註冊流程在哪流失

查詢模式：session 級 funnel JOIN。需要 PostgreSQL 層。

 1-- PostgreSQL
 2WITH session_steps AS (
 3  SELECT session_id, name,
 4         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 5  FROM events
 6  WHERE name IN ('signup.start', 'signup.email', 'signup.verify', 'signup.complete')
 7    AND ts >= NOW() - INTERVAL '30 days'
 8)
 9SELECT name, COUNT(DISTINCT session_id) as sessions
10FROM session_steps
11GROUP BY name
12ORDER BY MIN(step_order);

完整的 funnel 分析方法論見 從 collector 資料做基礎 funnel 分析。

需要的事件

安全審計查詢

安全審計查詢回答「有沒有非預期的存取」。重點是偵測異常模式而非單筆事件。

查詢場景

有沒有異常登入

查詢模式：auth 失敗事件按 session 分群計數，短時間內大量失敗 = 暴力破解嘗試。

1-- SQLite
2SELECT session_id, COUNT(*) as fail_count,
3       MIN(ts) as first_attempt, MAX(ts) as last_attempt
4FROM events
5WHERE type = 'error' AND name = 'auth.login.failed'
6  AND ts >= datetime('now', '-1 hour')
7GROUP BY session_id
8HAVING fail_count > 5;

誰存取了什麼敏感資料

查詢模式：敏感操作的 audit trail — 按時間列出所有敏感操作事件。

1-- SQLite
2SELECT ts, session_id, name, data
3FROM events
4WHERE type = 'event'
5  AND name IN ('data.export', 'admin.user_lookup', 'config.secret_read')
6ORDER BY ts DESC;

需要的事件

安全事件的取樣率必須是 1.0（全收）— 取樣會讓攻擊嘗試在統計上隱形。見 感測器生命週期管理 的取樣率設計段。

效能查詢

效能查詢回答「系統有多快」和「哪裡變慢了」。

查詢場景

P95 回應時間趨勢

查詢模式：時間分桶 + percentile 聚合。需要 PostgreSQL 層。

1-- PostgreSQL
2SELECT date_trunc('hour', ts) as hour,
3       percentile_cont(0.95) WITHIN GROUP (ORDER BY (data->>'duration_ms')::int) as p95
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= NOW() - INTERVAL '7 days'
7GROUP BY hour
8ORDER BY hour;

SQLite 沒有內建 percentile 函數。SQLite 層的替代方案是排序後取第 95% 位置的值，但在大資料量時效能差。

哪個版本變慢了

查詢模式：按 source.version 分群比較效能。

1-- SQLite / PostgreSQL
2SELECT source_version, AVG((data->>'duration_ms')::int) as avg_ms,
3       COUNT(*) as sample_count
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY source_version;

需要的事件

查詢 → 事件反推表

設計事件時用這張表反向確認：每種查詢場景需要什麼事件、什麼欄位、什麼 storage 層級。

這張表和 事件枚舉與補齊檢查 的事件表互補 — 事件枚舉從操作端正向推導「要收什麼」，本表從查詢端反向確認「收的夠不夠」。

下一步路由

• 從操作端正向推導事件 → 事件枚舉與補齊檢查
• 動機和事件的對應關係 → 動機驅動的事件設計
• SQLite vs PostgreSQL 的查詢能力分界 → 功能分層與 Backend 選擇
• Rule engine 的即時評估 → Rule engine 設計

為什麼查詢反模式比 vendor 細節更重要

多數團隊面對「資料庫變慢」時，會先去看 vendor 的調校（buffer pool、配置升級、replica 加開）。這些調校通常把基礎效能拉高 1-2 倍；一個 N+1 query 反模式可以讓回應時間慢 10-1000 倍（具體倍數取決於 N 跟 RTT — N=100 + RTT=1ms 約慢 100 倍）。先解掉應用層的反模式、再去調 vendor 配置，整體效益遠高於反過來。

這條優先序也對應 9.5 瓶頸定位流程 的精神：先定位真正的瓶頸再決定是否加資源。應用層 query 是最常被忽略的瓶頸來源。

N+1 Query：最常見也最隱性的反模式

N+1 query 指「先發一個 query 取回 N 筆資料、再對每一筆各發一個 query 取相關資料」，總共 1 + N 次 round trip。N 越大、整體越慢。

典型範例：列出 100 個訂單跟每筆訂單的客戶資料。錯誤寫法是先 SELECT * FROM orders LIMIT 100 拿到 100 筆訂單、再對每一筆訂單做 SELECT * FROM customers WHERE id = ?，總共 101 次 query。正確寫法是 JOIN 或 IN 一次取回：SELECT o.*, c.* FROM orders o JOIN customers c ON o.customer_id = c.id LIMIT 100，1 次 query 完成。

N+1 在 ORM 環境特別隱性，因為它常被框架的 lazy loading 機制隱藏。Django ORM 的 order.customer 看起來像存取 attribute，背後對應一次 query。寫程式時看不到 SQL，發布後才從 slow log 發現問題。

判讀方式：開啟 ORM 的 query log（debug mode）、看一個 API request 跑出幾個 query。預期是個位數；若 query 數隨著資料集大小線性成長（例如 list 100 筆觸發 100 query、list 1000 筆觸發 1000 query），這條 scaling 訊號就是 N+1 — 比固定閾值更可靠的判讀。

修正方向：

• ORM 端用 eager loading（Django select_related / prefetch_related、Rails includes、SQLAlchemy joinedload）
• 自己寫 SQL 用 JOIN 或 IN 條件批次取
• 確認 ORM 預設不是 lazy（有些 ORM 的設計鼓勵 lazy，需要明確標示 eager）

Select * 與超量讀取

SELECT * 把表的所有欄位都拉出來，包含可能很大的欄位（content、blob、JSON）跟根本用不到的欄位。代價有三：

1. 網路傳輸成本：query 結果在 DB 跟應用之間傳輸，欄位越多越大。
2. 記憶體成本：應用程式要 deserialize 整個 row，物件越大記憶體佔越多。
3. 隱性耦合：欄位有變動（新增、刪除、改型別）時，所有 SELECT * 的 query 都會被影響。

修正方向是明確列出需要的欄位：SELECT id, name, status FROM orders。如果擔心欄位列表太長，問自己是不是 query 試圖一次處理太多責任。

例外是 ad-hoc query 跟 DB tool 環境，可以接受 SELECT *。production code 不應該有。

缺索引：查詢計畫沒走索引

缺索引的徵兆是 query 在小資料量時很快、資料一多就突然慢。原因是 query 走了 full table scan，資料量小時 scan 還快、資料量上百萬筆就慢。

判讀方式是用 EXPLAIN 看查詢計畫：

• type=ALL 或 Seq Scan 代表沒走索引
• rows 估計值跟實際表大小接近，代表掃描範圍過大
• Using filesort / Using temporary 代表排序或暫存資料的成本

修正方向不是「對每個 WHERE 條件都建索引」，這會讓寫入變慢、索引變大。要建索引的判讀條件：

• 該 query 是熱路徑（頻率高、影響 user）
• 該欄位有足夠選擇性（distinct 值多）
• 該欄位沒有跟其他索引重複覆蓋
• 寫入路徑能承受多一個索引的維護成本

複合索引的欄位順序也要對齊 query 的 WHERE 條件。WHERE a = ? AND b = ? 適合 (a, b) 複合索引，不適合 (b, a)。這部分屬於 1.2 schema design 與資料建模 的範圍、本章只標出徵兆跟診斷起點。

ORM Lazy Load 陷阱

ORM 的 lazy load 預設行為是「存取 attribute 時才發 query」，這在開發時讓 code 很乾淨，但隱藏了 query 的數量。

常見陷阱：

• 跨 transaction 邊界存取 lazy attribute：query 在原 transaction 已關閉後才發，連線狀態錯誤。
• 在 template / serializer 裡存取 lazy attribute：一個 page render 觸發數十個額外 query。
• lazy load 跨服務邊界：DTO 傳遞時不知道哪些 attribute 是 lazy、哪些是 eager，前端拿到 DTO 後 trigger 額外 query。

修正方向：

• 明確標示 eager loading 邊界，serializer 之前完成所有需要的資料載入
• ORM 配置改成 default eager 或 strict mode（query 太多會 warning）
• DTO 出 service 邊界前做 fully materialized

Long-Running Transaction

長時間佔住的 transaction 會擋住其他 query、產生 lock 等待、消耗連線池資源。

常見成因：

• 在 transaction 內做 HTTP call 或外部 API 呼叫
• 在 transaction 內做檔案 I/O 或長計算
• 用 transaction 包住整個 request handler（從 request 開始到 response 結束都在 transaction）
• ORM 設定 default transaction-per-request 但業務只需要短交易

修正方向是把 transaction 範圍縮到最小：只包住「需要原子性」的那幾個 SQL 操作。外部呼叫、計算、檔案 I/O 都要在 transaction 之外。詳見 1.3 transaction 與一致性邊界。

其他常見反模式

上面五個是讀路徑高頻反模式。實務上其他幾類在 slow log 出現頻率不低、要一併列入發布前檢查：

• Cardinality explosion / cross join 誤用：兩個多對多關聯 join 沒加 filter、結果集從 N 行炸成 N×M 行。判讀訊號：query 結果行數遠超業務直覺、EXPLAIN 估計 rows 異常大。修正方向：補 filter、改 EXISTS / IN 半連接、或拆兩段 query。
• OFFSET-based pagination on large tables：LIMIT 20 OFFSET 100000 在大表退化成「掃描 100020 行 + skip 100000 行」。修正方向：用 keyset / cursor pagination（WHERE id > last_seen_id LIMIT 20）— 一致 O(LIMIT) 而非 O(OFFSET + LIMIT)。
• 隱式型別轉換讓 index 失效：WHERE varchar_col = 123 把 column 轉成 int 比較、index 失效退到 full scan。判讀訊號：EXPLAIN 顯示 index 沒命中但 schema 上有 index。修正方向：明示型別（WHERE varchar_col = '123'）。
• 應用層做大結果集排序 / 聚合：把 100 萬行拉回應用、在記憶體 sort 或 group。應該 push 給 DB 做 ORDER BY / GROUP BY + LIMIT。判讀訊號：應用程式記憶體用量隨 endpoint 流量線性升高。
• N+1 write：在 loop 內單筆 insert / update 而非 bulk insert。每筆觸發一次 round trip + 可能的 fsync。修正方向：用 INSERT ... VALUES (), (), () 或 executemany / bulk_create。

NoSQL / KV DB 也有 sibling 反模式（hot partition、read amplification、scan-and-filter），不在本章 SQL 範疇但邏輯類似 — 詳見 1.10 KV / Document DB 容量規劃。

每請求的 Query 預算

把上面這些反模式收斂成一個發布前可檢查的判準：每個 API request 允許發多少個 query。

超過預算不一定錯，但需要解釋。CI / staging 可以加 middleware 統計每個 endpoint 的 query 數，超過閾值在 PR review 時觸發討論。這比事後從 slow log 找問題更有效。

這張表以 OLTP API 為主。Dashboard / report / search endpoint 常需要 10-30 query 解 join / aggregation、用「Complex」涵蓋不夠精確；batch / bulk write（一次寫入 1000 筆訂單）不該用 query count 評估、應該看 batch size 跟 transaction 範圍。預算是判讀工具、不是硬閾值。

判讀訊號

常見誤區

把「資料庫變慢」直接解讀成「該升級資料庫」。先看應用層 query。多數效能問題是反模式造成的、而不是 DB 規格不夠。

把索引當「想加就加」。每個索引都有寫入成本跟空間成本。索引太多會讓 INSERT/UPDATE 變慢、backup 變大。要建索引前先驗證該 query 是熱路徑。

把 N+1 當「在 ORM 環境無解」。多數 ORM 都有 eager loading 選項，只是預設 lazy。問題是團隊沒把這當作預設策略。設定 ORM 為 default eager 或在 CI 加 query 數量檢查就能避免。

把 transaction 範圍當「越大越安全」。長 transaction 是 lock 風險來源，不是一致性保證。一致性靠正確的 isolation level 跟業務邏輯，不是靠長 transaction 鎖住整個流程。

定位邊界

本章專注「應用層發給資料庫的 query 反模式」。當問題進入 schema 設計（要不要拆表？要不要 partition？）交給 1.2 schema design；進入 transaction 語意（什麼時候用 SERIALIZABLE？怎麼 retry？）交給 1.3 transaction boundary；進入跨服務的查詢責任拆分（哪些查詢屬於該服務？）交給 1.8 state ownership 與 query boundary；進入瓶頸定位的工程流程交給 9.5 瓶頸定位流程。

案例回寫

09 案例庫的主軸是規模、vendor 與容量壓力，直接以「query 反模式」為主題的案例較少。下列案例可以反向讀：每一個都展示了「在沒有先用 query 反模式優化收回壓力的前提下、團隊直接走 vendor 遷移或 scale-out 路徑」的決策。讀者讀完應追問：這些 case 啟動遷移前、是否有可能用本章的反模式清單先收回一部分容量？

• 9.C39 DoorDash：Aurora Postgres 寫入瓶頸 → CockroachDB — DoorDash 撞到 Aurora single-primary write 天花板（瓶頸在 primary CPU + WAL flush rate）、用 PostgreSQL wire protocol 相容的 CockroachDB 換成多主寫入、ORM 不必重寫。對照本章可問：寫入熱點是否伴隨長 transaction 或熱 row 競爭？這些是 vendor 遷移前可以先用本章「Long-Running Transaction」清單檢查的點。
• 9.C20 Zomato：TiDB 遷到 DynamoDB — Zomato 判斷 billing 事件本身可接受 eventually consistent、用一致性語意換取 4 倍吞吐 + 50% 成本。對照本章可問：遷移前每筆業務動作平均發了多少 query、是否有 N+1 或 select * 在放大壓力？把這條問題擺進「每請求 Query 預算」段一起讀。
• 9.C14 Standard Chartered：Aurora 4000 TPS 合規容量 — Standard Chartered 在 7 個受監管市場各跑獨立 Aurora cluster（資料不能跨境）、容量規劃單位是「per 市場」、合規邊界決定了 cluster 拓樸。對照本章可問：query 預算假設是否進入容量模型？預算寫鬆、規劃出的 per-cluster TPS 上限會偏低。

DoorDash 案例是這條反向追問最直接的應用 — 寫入瓶頸的判讀不該停在 vendor 規格、而是先檢查 transaction 範圍跟熱 row 競爭。Zomato 跟 Standard Chartered 的反向追問則退一步問「query 預算假設是否進入容量模型」。三條追問共享同一條診斷邏輯：應用層 query 不是事後解釋的細節、是事前可以收回的容量。這個讀法承認案例本身不直接示範 query 反模式、是用反向追問把案例當成 query 反模式重要性的反證。

跨模組路由

1. 與 1.1 高併發下的 SQL 讀寫邊界 的交接：1.1 處理連線池與 read replica 機制、1.13 處理 query 寫法本身。高併發場景下兩者要同步檢查。
2. 與 1.2 schema design 的交接：索引設計是 schema 層的事、本章只指出徵兆。
3. 與 04 observability 的交接：slow query log、APM、query trace 是判讀反模式的主要訊號來源。
4. 與 9.5 瓶頸定位流程 的交接：先在應用層查反模式，再考慮 DB 配置升級。
5. 與 9.13 擴展軸 的交接：規模成長路線上、9.13 解擴展軸選擇後、1.13 是緊接著的下一站 — 在加機器或加 replica 前、先用本章反模式清單收回單機能撐住的容量。
6. 與 10.1 服務拆分 的交接：拆服務常被用來「解決 DB 慢」，但本章的反模式優化通常比拆服務 ROI 更高、應該優先嘗試。

下一步路由

規模成長路線下一站 → 1.1 高併發下的 SQL 讀寫邊界：query 反模式收完後、處理連線池與 read replica 的擴展。

其他延伸方向：

• Schema 與索引設計 → 1.2 schema design 與資料建模
• Transaction 範圍收斂 → 1.3 transaction 與一致性邊界
• 瓶頸定位完整流程 → 9.5 瓶頸定位流程