Telemetry 的 DataFusion SQL 參考
完整的 Telemetry SQL 參考 介紹了 Telemetry 內建的查詢引擎，包括語法、型別、運算子、純量函式、彙總、視窗函式和巢狀資料。此舊頁面保留了可透過書籤存取的範例，描述的是使用 Apache DataFusion 45.2.0 的公開配方測試套件所驗證的模式。該測試引擎與 Telemetry 的正式環境分支不同。
欄位名稱和型別仍然來自您的事件合約。使每個範例適應應用程式實際使用的資料表、單位、狀態、標識規則和時間語義。
從有界讀取開始
操作查詢通常應以 UTC 時間過濾器開始，並僅返回問題所需的欄位：
SELECT
route_template,
status_code,
latency_ms,
timestamp_utc
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC
LIMIT 100;
timestamp_utc 是伺服器管理的查詢時間戳。源提供的 timestamp 欄位在攝取過程中進行標準化，不應替換配方中生成的查詢列。
檢查原始行時使用 LIMIT。對於完整匯出，請使用 非同步查詢API，而不是從互動式查詢中刪除所有防護措施。
建立完整的時間段
date_trunc 為趨勢創造了穩定的顆粒：
SELECT
date_trunc('hour', timestamp_utc) AS hour,
COUNT(*) AS requests
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;
最新的一小時或一天可能仍然很滿。當部分容量會使結果產生誤導時，從警示中排除該儲存桶。在每次比較中使用相同的時區、儲存桶大小和完整性規則。
條件計數和安全率
條件 CASE 表示式計算同一分組行的多個結果：
SELECT
route_template,
COUNT(*) AS requests,
SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC;
NULLIF 保護分母為零的除法。乘以 100.0 可防止百分比算術變成整數除法。 HAVING 最小值可防止安靜組中的一個故障的排名超過繁忙路由併產生有意義的影響。
百分位數和分佈
使用 approx_percentile_cont(latency_ms, 0.95) 進行有效的 p95 估計：
SELECT
route_template,
approx_percentile_cont(latency_ms, 0.50) AS p50_ms,
approx_percentile_cont(latency_ms, 0.95) AS p95_ms,
approx_percentile_cont(latency_ms, 0.99) AS p99_ms
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template;
將 p50 與 p95 或 p99 進行比較。整個發行版的類似成長表明工作流程普遍較慢；較大的尾部變化表明存在異常緩慢的操作的子集。百分位數是估計值，因此請避免呈現微不足道的小數精度。
對於類似直方圖的結果，請使用 CASE 將數值分配給顯式儲存桶。將儲存桶標籤和排序列分開，以便 "1000+" 不會在 "250-499" 之前排序。
使用 CTE 為每項計算命名
公共資料表表示式將業務定義與最終聚合分開：
WITH account_activity AS (
SELECT
account_id,
MIN(CASE WHEN event_name = 'signup_completed' THEN timestamp_utc END)
AS signed_up_at,
MIN(CASE WHEN event_name = 'activation_completed' THEN timestamp_utc END)
AS activated_at
FROM product_events
WHERE timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY account_id
)
SELECT
COUNT(*) AS signed_up_accounts,
SUM(CASE WHEN activated_at IS NOT NULL THEN 1 ELSE 0 END)
AS activated_accounts
FROM account_activity
WHERE signed_up_at IS NOT NULL;
透過臨時從中選擇來檢查中間 CTE。這通常是捕獲重複標識、意外空值或包含錯誤行的里程碑定義的最快方法。
連線需要明確的粒度
在連線事件資料表之前，請說明每一行代表什麼。多對多聯接可以增加計數，同時仍返回有效的 SQL。
當作為分析單位時，在加入之前將每個帳戶、請求、作業、Webhook 交付或計費週期預先聚合到一行。使用為關聯而建立的穩定識別符號，切勿僅僅因為顯示標籤看起來唯一而加入它。
連線後，比較：
- 之前和之後的行數
- 之前和之後的不同識別符號計數
- 兩側不匹配的行
- 與已知結果的賽程的總計
視窗函式
視窗函式在比較相鄰值時保留行或儲存桶的詳細資訊：
WITH daily AS (
SELECT
date_trunc('day', timestamp_utc) AS day,
COUNT(*) AS completed_jobs
FROM job_events
WHERE status = 'completed'
AND timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY date_trunc('day', timestamp_utc)
)
SELECT
day,
completed_jobs,
LAG(completed_jobs) OVER (ORDER BY day) AS previous_day_jobs,
AVG(completed_jobs) OVER (
ORDER BY day
ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
) AS rolling_7_bucket_average
FROM daily
ORDER BY day;
LAG 公開以前的值。帶框架的 AVG 建立滾動基線。前面幾排的窗戶不完整；在建立警示之前決定是顯示它們、抑制它們還是標記它們。
巢狀欄位和識別符號
Telemetry 將巢狀物件儲存為 Arrow 結構。使用實際的結構路徑存取巢狀欄位，例如 data.tool.name；而 "data.tool.name" 表示名稱中包含字面點號的單一欄位。複製巢狀欄位查詢之前，請閱讀巢狀資料並檢查資料表結構。
設計新事件時，使用 Snake_case 欄位名稱並避免保留或不明確的單詞。如果現有欄位需要引用，請一致地引用它，而不是建立同一概念的兩種拼寫。
支援的模式和固定限制
測試的配方套件練習 SELECT、CTE、連線、CASE、常見聚合、date_trunc、間隔、近似百分位數、LAG、框架視窗、NULLIF、COALESCE、排序、分組和限制。
DataFusion 不是 PostgreSQL、MySQL、BigQuery 或 Snowflake。外觀相似的函式可以有不同的名稱或簽名。 Telemetry 的配方審查使用的固定計劃程式不接受這些系統中找到的每個聚合修改器或日期幫助程式。首選本參考文獻和經過測試的 SQL配方庫 中示範的語法，然後在改編另一種方言的範例之前執行一個小型查詢。
查詢審查清單
在儲存查詢或在警示中使用它之前：
- 確認資料表、列、型別、單位和 UTC 時間範圍。
- 定義參與者或工作流程識別符號並驗證行粒度。
- 決定重試、重複、延遲事件、空值和不完整儲存桶的行為方式。
- 透過分母檢查和最小有意義的數量來保護比率。
- 檢查中間 CTE 和連線行數。
- 測試綜合成功、失敗、重試、重複和邊界情況。
- 在結果旁邊記錄定義、所有者、閾值和預期回應。
每個配方都包含模式、可複製的 SQL、確定性合成輸出、視覺化、解釋註釋、邊緣案例、儀表板建議和警示指導。讀取 SQL測試方法，然後從 API 可靠性、產品分析、資料品質 或 基礎設施 開始。