TDengine 时序函数 SAMPLE 用户手册
SAMPLE
1. 函数概述
| 项目 | 说明 |
|---|---|
| 函数名称 | SAMPLE |
| 功能说明 | 从查询结果或分组中随机抽取最多 k 条非 NULL 样本（使用水库抽样）。 |
| 语法 | SAMPLE(expr, k) |
| 参数 | expr 任意类型列或表达式；k 采样条数，1≤k≤1000，浮点向下取整。 |
| 返回类型 | 与 expr 相同 |
| 适用范围 | 表、超级表、子查询 |
| 兼容特性 | 支持 WHERE、PARTITION BY、GROUP BY、INTERVAL、STATE_WINDOW、SESSION_WINDOW 等场景 |
2. 函数意义与应用
- 快速抽样检视海量数据，验证数据质量或趋势。
- 超级表多设备抽查，监测异常值分布。
- 与窗口查询配合，从固定时间段内提取代表性记录。
3. 参数与行为
expr支持所有标量类型、表达式与标签列。k为正数，>1000 触发错误；浮点被向下取整。- 若可用非 NULL 行数 <
k，返回全部；若无非 NULL 行则结果为空。 - 抽样顺序与最终
ORDER BY无关，排序在采样后执行。
4. 使用注意
- 每个
SELECT只能出现一次 SAMPLE。 - 不可与聚合函数混写在同一列输出（例如
SELECT SAMPLE(c,2), MAX(c)报错）。 - 不能在
WHERE直接调用（需用子查询）。 - 超级表使用时推荐
PARTITION BY tbname，必要时可与标签GROUP BY结合。 - 可与时间窗口(
INTERVAL/STATE_WINDOW/SESSION_WINDOW)联用。
5. 抽样原理
内部采用水库抽样：逐行扫描输入，保证每条记录以 k/n 概率入样，重复执行结果可能不同；同一时间戳的复合主键，取最小键行参与抽样。
6. 计算流程示例
给定 6 条电压数据（含 1 个 NULL），执行 SAMPLE(voltage,3) 时：
- 顺序读取非 NULL 行：4、2、1、5、3 形成候选池。
- 运行水库抽样后随机保留 3 条，如 {4,1,5}。
- 输出时附带其他已选列或时间戳（若查询中包含）。
7. 示例（含场景说明）
-- 示例1：基础抽样（随机取 5 条 c1）——快速预览表数据
SELECT SAMPLE(c1, 5) AS sample_c1
FROM d1;
-- 示例2：条件过滤后抽样——仅在速度>40的样本中抽 3 条
SELECT SAMPLE(speed, 3) AS speed_sample
FROM vehicle
WHERE speed > 40;
-- 示例3：超级表按子表抽样——每个子表返回最多 2 条，检查各设备状态
SELECT SAMPLE(voltage, 2) AS v_sample
FROM meters
PARTITION BY tbname;
-- 示例4：结合 INTERVAL 窗口——每10分钟窗口抽 1 条样本，代表各窗口数据
SELECT _wstart, SAMPLE(power, 1) AS power_sample
FROM meters
WHERE ts >= NOW() - 1h
INTERVAL(10m);
-- 示例5：STATE_WINDOW 窗口抽样——按状态切分后抽 2 条，分析状态段数据
SELECT SAMPLE(current, 2) AS current_sample
FROM meters
STATE_WINDOW(current > 20);
-- 示例6：子查询与排序——先抽样，再按时间倒序取最近 2 条展示
SELECT *
FROM (SELECT ts, SAMPLE(temp, 10) AS temp_sampleFROM d1
) t
ORDER BY ts DESC
LIMIT 2;