ドキュメントを見る

概念とSQLパターン更新日: 2026年7月28日Telemetry 編集チームと製品チームによるレビュー4 最小読み取り時間

コーディングエージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディングエージェント用の集中プロンプトパックを開き、それをここで説明するワークフローに適応させます。

このページの内容

境界付き読み取りから開始する
完全なタイムバケットを作成する
条件付きカウントと安全率
パーセンタイルと分布
CTE は定義をレビュー可能にします
結合には明示的なグレインが必要です
ウィンドウ関数
ネストされたフィールドと識別子
サポートされているパターンと固定された制限
クエリレビューチェックリスト

Telemetry向けDataFusion SQLリファレンス

Telemetry は、Apache DataFusion SQL を使用して構造化イベントテーブルをクエリします。 Telemetry の公開レシピは現在、次のように計画され、実行されています。 アパッチ DataFusion 45.2.0 出版前に。このリファレンスでは、固定されたテストスイートによって実行されるパターンについて説明します。

フィールド名とタイプは引き続きイベントコントラクトから取得されます。すべての例を、アプリケーションが実際に使用するテーブル、単位、ステータス、アイデンティティルール、および時間セマンティクスに適応させます。

境界付き読み取りから開始する

操作クエリは通常、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 最小限に抑えることで、静かなグループ内の 1 つの障害が混雑したルートを上回って重大な影響を与えることを防ぎます。

パーセンタイルと分布

使用する 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 を一時的に選択して検査します。多くの場合、これは、重複した ID、予期しない null、または間違った行を含むマイルストーン定義を検出する最速の方法です。

結合には明示的なグレインが必要です

イベントテーブルを結合する前に、各側の 1 行が何を表すかを述べます。多対多の結合では、有効な SQL を返しながらカウントを乗算できます。

分析の単位である場合は、参加する前に、アカウント、リクエスト、ジョブ、Webhook 配信、または請求期間ごとに 1 行に事前に集計します。相関のために作成された安定した識別子を使用し、一意に見えるという理由だけで表示ラベルに結合しないでください。

結合後、以下を比較します。

前後の行数
前後の個別の識別子の数
両側で一致しない行
結果がわかっているフィクスチャに対する合計

ウィンドウ関数

ウィンドウ関数は、隣接する値を比較している間、行またはバケットの詳細を保持します。

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 は、点線のフィールドパスを通じてネストされた JSON を公開します。現在のテーブルスキーマで点線のパスを引用符で囲む必要がある場合は、次のような二重引用符で囲まれた識別子を使用します。 "data.tool.name"。読むネストされた JSON のクエリネストされたフィールドクエリをコピーする前に、テーブルスキーマを検査します。

新しいイベントを設計するときは、snake_case フィールド名を使用し、予約語や曖昧な単語を避けてください。既存のフィールドで引用が必要な場合は、同じ概念の 2 つの綴りを作成するのではなく、一貫して引用してください。

サポートされているパターンと固定された制限

テストされたレシピスイートの演習 SELECT、CTE、結合、 CASE、一般的な集計、 date_trunc、間隔、おおよそのパーセンタイル、 LAG、枠付き窓、 NULLIF, COALESCE、順序付け、グループ化、および制限。

DataFusion は、PostgreSQL、MySQL、BigQuery、または Snowflake ではありません。見た目が似ている関数でも、名前やシグネチャが異なる場合があります。 Telemetry のレシピ監査で使用される固定プランナーは、これらのシステムで見つかったすべての集計修飾子や日付ヘルパーを受け入れるわけではありません。このリファレンスと、テスト済みの SQL レシピライブラリ、別の方言の例を適用する前に、小さなクエリを実行します。

クエリレビューチェックリスト

クエリを保存する前、またはアラートで使用する前に、次のことを行ってください。

テーブル、列、タイプ、単位、UTC 時間範囲を確認します。
アクターまたはワークフローの識別子を定義し、行粒度を確認します。
再試行、重複、遅延イベント、NULL、および不完全なバケットの動作を決定します。
分母チェックと意味のある最小限のボリュームで比率を保護します。
中間の CTE と結合された行数を検査します。
合成の成功、失敗、再試行、重複、境界のケースをテストします。
結果の横に、定義、所有者、しきい値、および予期される応答を記録します。

すべてのレシピには、スキーマ、コピー可能な SQL、決定論的な合成出力、視覚化、解釈メモ、エッジケース、ダッシュボードの提案、アラートガイダンスが含まれています。読んでください SQL テスト方法、次に始めます API の信頼性, 製品分析, データ品質、またはインフラストラクチャ.

所有権と技術リファレンス

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

編集基準を見直す

Apache DataFusion SQL リファレンス

コーディング エージェントでこのドキュメントを使用してください