KWDB SampleDB 上新｜新增窗口函数示例

时序数据的分析难点，往往不在于单点查询，而在于如何在连续的数据流中划出有意义的“片段”。一辆车减速了多久？设备掉线间隔有多长？某个状态持续了几条记录？这类问题，传统的 GROUP BY
 加固定时间并不够用。

KWDB 的分组窗口函数（Group Window Function）是专为时序表设计的聚合机制。与传统数据库的解析窗口函数（OVER
 子句）不同，它通过 GROUP BY
 子句指定切分规则，对每个窗口独立输出一行聚合结果。

语法结构如下：

SELECT select_list
FROM ts_table
[WHERE condition]
GROUP BY [<ptag>,] group_window_function;

其中 group_window_function
 可以是以下五种之一：

COUNT_WINDOW(count_val[, sliding_val])
EVENT_WINDOW(start_trigger_condition, end_trigger_condition)
SESSION_WINDOW(ts_col, tol_val)
STATE_WINDOW(column_name)
TIME_WINDOW(ts_col, duration[, sliding_time])

使用前有几个前提需要明确：

• 仅支持时序表单表查询，不支持嵌套、关联或联合查询。

• 必须出现在 `GROUP BY` 子句中，可以单独使用，也可与主标签（ptag）组合。

• 表内单个设备的数据应按时间戳有序且不重复。

SampleDB 的窗口函数示例使用了一张名为 ts_window.vehicles
 的时序表，模拟路边检测点采集的车辆过车数据：

CREATE TS DATABASE ts_window;
CREATE TABLE ts_window.vehicles (
  ts        timestamp NOT NULL,
  vehicle_id varchar(16),
  speed     float,
  lane_no   int
) TAGS (
  location int NOT NULL
)
PRIMARY TAGS(location);

示例中共有 6 条数据：

6 条记录，时间跨度约 20 分钟，车速在 25～40 之间波动。这份数据看似简单，却足够演示所有 5 种窗口切分逻辑的差异。

 1. COUNT_WINDOW：按行数切分 

最直观的窗口类型——每 N 条记录划为一个窗口，也支持滑动步长。

场景：统计每 3 条过车记录的平均车速。

SELECT
  count(ts) AS records,
  avg(speed) AS avg_speed
FROM ts_window.vehicles
GROUP BY COUNT_WINDOW(3);

6 条数据被平均切成 2 个窗口，每组各 3 条。如果加上滑动参数，每 2 条滑动一次，窗口之间会有重叠：

GROUP BY COUNT_WINDOW(3, 2)

注意：滑动值必须为正整数，且不能大于窗口行数。

 2. EVENT_WINDOW：按事件条件切分 

EVENT_WINDOW
 最适合捕捉“从某个状态到另一个状态”的完整过程。它接受两个条件表达式：开始触发条件和结束触发条件。

场景：识别低速拥堵事件——速度低于 30 时拥堵开始，速度回升到 35 及以上时拥堵结束。

SELECT
  count(ts) AS records,
  avg(speed) AS avg_speed
FROM ts_window.vehicles
GROUP BY EVENT_WINDOW(speed < 30, speed >= 35);

这种窗口天然契合异常检测、告警区间分析等场景，能把“一段时间内的连续异常”作为整体聚合，而不是被固定时间槽割裂。

 3. SESSION_WINDOW：按时间间隔切分会话 

SESSION_WINDOW
 模仿的是会话（Session）概念：只要相邻两条记录之间的时间间隔不超过容忍阈值，就认为它们属于同一个会话；一旦超出阈值，会话断开，下一条记录开启新会话。

场景：按 5 分钟最大连续间隔划分车流会话。

SELECT
  count(ts) AS records,
  avg(speed) AS avg_speed
FROM ts_window.vehicles
GROUP BY SESSION_WINDOW(ts, '5m');

结合示例数据逐条看间隔：12:01→12:02 间隔 1 分钟，同一会话；12:02→12:09 间隔 7 分钟，超过 5 分钟阈值，会话断开；12:09→12:11 间隔 2 分钟，开启新会话；12:11→12:12 间隔 1 分钟，同一会话；12:12→12:21 间隔 9 分钟，再次断开。最终切出 3 个会话：{12:01, 12:02}
、{12:09, 12:11, 12:12}
、{12:21}
。

注意：间隔参数支持 s
、m
、h
、d
、w
，不支持 1m2s
 这类复合格式。

 4. STATE_WINDOW：按状态值变化切分 

STATE_WINDOW
 监控某列（或表达式）的状态值，只要值不变就保持在同一窗口；一旦值发生变化，就切分出新窗口。这在设备状态追踪、运行模式分析中非常实用。

场景：将“低速（< 35）”与“非低速”作为状态量，分析各状态持续了多少条记录。

SELECT
  count(ts) AS records,
  avg(speed) AS avg_speed
FROM ts_window.vehicles
GROUP BY STATE_WINDOW(CASE WHEN speed < 35 THEN 'low' ELSE 'high' END);

提示：STATE_WINDOW
 适合整型、布尔值和字符类型的状态列，不建议直接作用于连续浮点值。

 5. TIME_WINDOW：按固定时间间隔切分 

TIME_WINDOW
 是最常见的时间分桶方式，将时间轴按固定间隔等分，每个桶独立聚合。也支持设置滑动时间来实现滑动窗口（窗口间有重叠）。

场景：按 10 分钟固定窗口统计车流量。

SELECT
  count(ts) AS records,
  avg(speed) AS avg_speed
FROM ts_window.vehicles
GROUP BY TIME_WINDOW(ts, '10m');

加上滑动参数，可以做每 5 分钟滑动一次的 10 分钟滑动窗口：

GROUP BY TIME_WINDOW(ts, '10m', '5m')

注意：滑动时间不应大于窗口大小，且两者差距也不建议过大。

04

五种窗口的横向对比

SampleDB 的 window/
 目录提供了完整的脚本，整个流程只需 4 步：

# 1. 启动 KWDB 单机服务
bash start_service.sh
# 2. 生成示例数据
bash generate_data.sh
# 3. 建库建表并导入数据
bash create_load.sh
# 4. 执行窗口函数示例查询
bash query.sh

也可以直接一键执行：

bash window_test.sh

前提：将 window/
 目录中的文件放到 KWDB 二进制目录下，且脚本仅支持 Linux 系统。

KWDB 的 5 种分组窗口函数各有侧重：TIME_WINDOW
 适合等时间槽统计，COUNT_WINDOW
 适合等样本量统计，SESSION_WINDOW
 适合活跃段识别，STATE_WINDOW
 适合状态跟踪，EVENT_WINDOW
 适合事件边界捕捉。

SampleDB 窗口函数示例提供了一个开箱即用的验证环境，无需自建数据，执行脚本即可复现所有查询结果。对于正在评估或使用 KWDB 时序能力的开发者来说，这份示例是一个不错的起点。

除了新增的时间窗口函数示例，我们也为原先的智能电表示例新增了时间窗口函数与电表场景结合的用例，KWDB Playground （https://github.com/KWDB/playground）项目也同步更新了窗口函数函数场景，欢迎体验。