使用时间戳

使用 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 时间函数获得更深入的见解，并根据您的数据做出更明智的决策。