ドキュメントを見る

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

タイムスタンプ付きイベントを再利用可能な操作ビューに変える

時間を認識する SQL を実行し、結果を検査し、分析をチームが再利用できるダッシュボードに保存します。

SQL ワークフローを探索する実際のテレメトリを接続する

このページの内容

タイムスタンプを一貫して保存する
時間関数を使用したクエリ
1.日付部分の抽出
2. 時間間隔ごとにグループ化する
3. 時間範囲を比較する
4. 時差を計算する
次のステップ

タイムスタンプの操作

Telemetry の DataFusion SQL エンジンで日ごとのイベント数を数え、週を比較し、イベント間の時間を測れます。以下にそれぞれの計算例を示します。

タイムスタンプを一貫して保存する

Telemetry は、すべてのイベントにタイムスタンプがあることを保証します。ペイロードが省略された場合 timestamp、ログ API に現在の UTC 時間が追加されます。ソースイベントの時刻が取り込み時刻と異なる場合は、タイムゾーンで修飾された ISO 8601 値または Unix タイムスタンプを指定することもできます。 Telemetry は最適化された timestamp_utc SQL 操作の列。

ログエントリの例:

{
  "event_id": "e12345",
  "event_type": "click",
  "user_id": "u67890",
  "timestamp": "2026-07-27T14:22:00.000Z",
  "metadata": {
    "browser": "Chrome",
    "device": "Mobile",
    "location": "New York"
  }
}

このログでは、ソースは独自のイベント時間を提供します。フィールドが省略された場合は、代わりに取り込み時間が使用されます。

時間ベースのデータのクエリ

使用する timestamp_utc フィルタリング、バケット化、並べ替え、および時間計算に使用します。これはネイティブ UTC タイムスタンプタイプを持ち、Telemetry テーブル全体で一貫したクエリ列です。

使用するメリット timestamp_utc:

特に大規模なデータセットの場合、クエリの実行が高速化されます。
コンパクトなタイムスタンプ形式によりストレージが最適化されます。
次のような時間ベースの操作に対応するDataFusion SQLエンジンとの互換性: DATE_TRUNC, EXTRACTなど。

送信する必要はありません timestamp 取り込み時に作成されたイベントの場合。送信する場合は、現地時間が曖昧にならないように、タイムゾーンで修飾された値を使用してください。

時間関数を使用したクエリ

1.日付部分の抽出

EXTRACT() はタイムスタンプの年や時刻などの一部を取り出します。DATE_TRUNC() は指定した時間単位の先頭に切り捨てます。

例：曜日の抽出

タイムスタンプから曜日を抽出するには、次を使用できます。

SELECT 
    EXTRACT(DOW FROM timestamp_utc) AS day_of_week
FROM 
    event_log

このクエリは、各イベントの曜日 (0 ～ 6) を返します。0 は日曜日を表し、6 は土曜日を表します。

2. 時間間隔ごとにグループ化する

時間関数の一般的な使用例の 1 つは、日、週、月などの特定の時間間隔でイベントをグループ化し、各期間中に発生したイベントの数を確認することです。

例: イベントを日ごとにグループ化する

イベントを日ごとにグループ化し、1 日あたりのイベント数をカウントするには、次を使用できます。 DATE_TRUNC():

SELECT 
    DATE_TRUNC('day', timestamp_utc) AS day,
    COUNT(*) AS event_count 
FROM 
    event_log 
GROUP BY 
    DATE_TRUNC('day', timestamp_utc) 
ORDER BY 
    day

このクエリは、タイムスタンプを日レベルに切り捨て、切り捨てられた日ごとにイベントをグループ化します。結果は、毎日発生したイベントの数です。

3. 時間範囲を比較する

また、ある週と次の週のイベントを比較するなど、異なる期間のデータを比較することもできます。

例: 前週の比較

異なる週のイベント数を比較するには、次を使用できます。

SELECT 
    DATE_TRUNC('week', timestamp_utc) AS week,
    COUNT(*) AS event_count 
FROM 
    event_log 
GROUP BY 
    DATE_TRUNC('week', timestamp_utc) 
ORDER BY 
    week;

このクエリでは、イベントが発生した週ごとにグループ化され、週ごとの傾向を分析できます。

4. 時差を計算する

PostgreSQL では AGE() でタイムスタンプの差を計算できます。DataFusion は AGE() に対応していないため、タイムスタンプを直接引き算します。

例: イベント間の時間差の計算

LAG() で前のイベントの時刻を取得し、現在のイベントの時刻から引きます。

たとえば、現在のイベントと前のイベントの差を秒単位で計算するには、次のようにします。

WITH ordered_events AS (
  SELECT
    event_id,
    timestamp_utc,
    LAG(timestamp_utc) OVER (ORDER BY timestamp_utc) AS previous_timestamp
  FROM event_log
)
SELECT
  event_id,
  timestamp_utc,
  previous_timestamp,
  date_part('epoch', timestamp_utc - previous_timestamp)
    AS seconds_since_previous_event
FROM ordered_events
ORDER BY timestamp_utc;

LAG 以前のイベント時間を取得し、 date_part('epoch', ...) タイムスタンプ間隔を合計秒数に変換します。最初の行には以前のタイムスタンプがないため、その差は null です。

次のステップ

SQL の時間関数は、時間ベースのデータを分析および管理するために不可欠なツールです。 DataFusion には他の SQL エンジンと比べて特定の制限がありますが、サポートされている関数を効果的に使用して、さまざまな時間間隔でデータをグループ化、切り捨て、分析することができます。毎日のイベントの追跡、週ごとの傾向の比較、イベント間の時間差の計算など、SQL は時間ベースのデータの可能性を最大限に引き出すために必要な機能を提供します。

Telemetry 内のこれらの強力な SQL 時間関数を活用して、より深い洞察を取得し、データに基づいてより多くの情報に基づいた意思決定を行います。

ページの著者と参考資料

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

ドキュメントのレビュー方法

Apache DataFusion SQL リファレンス