使用時間戳

使用 Telemetry 的 DataFusion SQL 引擎按天統計事件、比較不同週的資料，或測量事件之間的時間間隔。以下範例分別展示這些計算。

一致地儲存時間戳

Telemetry 確保每個事件都有時間戳。如果有效負載省略 timestamp，則日誌 API 會新增當前 UTC 時間。當源事件時間與攝取時間不同時，您還可以提供時區限定的 ISO 8601 值或 Unix 時間戳。 Telemetry 公開了用於 SQL 操作的最佳化 timestamp_utc 色譜柱。

日誌條目範例：

{
  "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.按時間間隔分組

時間函式的一個常見用例是按特定時間間隔（例如天、周或月）對事件進行分組，以檢視每個時間段內發生了多少事件。

範例：按天對事件進行分組

要按天對事件進行分組並計算每天的事件數，您可以使用 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', ...) 將時間戳間隔轉換為總秒數。第一行沒有先前的時間戳，因此其差異為空。

後續步驟

SQL中的時間函式是分析和管理基於時間的資料不可或缺的工具。雖然 DataFusion 與其他 SQL 引擎相比有一定的侷限性，但您仍然可以有效地使用其支援的功能來分組、截斷和分析不同時間間隔的資料。無論您是追蹤每日事件、比較每週趨勢還是計算事件之間的時間差，SQL 都提供必要的功能來釋放基於時間的資料的全部潛力。

利用 Telemetry 中強大的 SQL 時間函式獲得更深入的見解，並根據您的資料做出更明智的決策。