TDengine 选择函数 TOP() 用户手册
TOP 函数用户手册
函数定义
TOP(expr, k)
功能说明
TOP() 函数返回指定列中最大的 k 个非 NULL 值及其对应的记录。如果多条数据取值相同，且全部取用会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。
版本要求
- 最低版本: v3.0.0.0
返回值
- 数据类型: 与输入参数相同的数据类型
- 返回内容: 最大的 k 个值及其对应的完整记录
参数说明
| 参数 | 类型 | 说明 | 取值范围 |
|---|---|---|---|
| expr | 表达式 | 要统计的字段表达式 | 数值类型 |
| k | 整数 | 返回的记录数量 | [1, 100] |
适用数据类型
TOP 函数支持以下数据类型：
- 数值类型: TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、UTINYINT、USMALLINT、UINT、UBIGINT
适用范围
- 表类型: 表和超级表
- 查询支持: 支持聚合查询、多行返回
- 函数特性: 聚合函数、选择函数、多行函数、保持顺序、忽略 NULL 值
基本用法示例
单列查询
-- 返回电流最大的 5 个值
SELECT TOP(current, 5) FROM meters;-- 返回电压最大的 3 个值
SELECT TOP(voltage, 3) FROM meters;-- 返回相位最大的 10 个值
SELECT TOP(phase, 10) FROM meters;
带时间戳查询
-- 返回电流最大的 5 个值及其时间戳
SELECT ts,TOP(current, 5) as top_current_values
FROM meters;
带标签查询
-- 返回包含标签信息的 TOP 查询
SELECT location,TOP(current, 5) as top_current_values,ts
FROM meters;
智能电表场景应用示例
基于智能电表数据库结构：
-- 数据库和表结构
USE test;
-- meters 超级表包含 ts, current, voltage, phase 字段和 location, groupid 标签
场景1：负载峰值分析
-- 查找全网电流最高的 10 个记录
SELECT TOP(current, 10), ts FROM meters;-- 查找电压最高的 5 个记录
SELECT TOP(voltage, 5), ts FROM meters;
场景2：按区域分组的峰值分析
-- 查找每个区域电流最高的 5 个值
SELECT location,TOP(current, 5),ts
FROM meters
GROUP BY location;-- 查找每个区域电压最高的 3 个值
SELECT location,TOP(voltage, 3),ts
FROM meters
GROUP BY location;
场景3：设备负载排名
-- 查找各电表电流最高的 3 个记录
SELECT tbname,location,TOP(current, 3),ts
FROM meters
GROUP BY tbname, location;
场景4：异常高值检测
-- 检测电流异常高值（前 20 个最高值）
SELECT tbname,location,TOP(current, 20),ts
FROM meters
GROUP BY tbname, location;
场景5：电网负荷热点分析
-- 分析各区域的负荷热点（前 10 个峰值）
SELECT location,TOP(current, 10),ts
FROM meters
GROUP BY location;
场景6：设备容量评估
-- 评估设备的负载容量使用情况（前 5 个峰值）
SELECT tbname,location,TOP(current, 5),ts
FROM meters
GROUP BY tbname, location;
场景7：时间段内的峰值分析
-- 分析最近一天内的负载峰值
SELECT location,TOP(current, 15),ts
FROM meters
WHERE ts >= NOW() - 1d
GROUP BY location;-- 分析最近一周的峰值趋势
SELECT location,TOP(current, 25),ts
FROM meters
WHERE ts >= NOW() - 7d
GROUP BY location;
场景8：电力质量监控
-- 监控电压质量（查找最高电压值）
SELECT tbname,location,TOP(voltage, 5),ts
FROM meters
GROUP BY tbname, location;
场景9：负载排行榜
-- 创建设备负载排行榜（前 50 个峰值）
SELECT tbname,location,groupid,TOP(current, 50),ts
FROM meters
GROUP BY tbname, location, groupid
LIMIT 20; -- 显示前 20 个设备
场景10：能耗分析与优化
-- 识别高能耗设备和时段
SELECT tbname,location,TOP(current, 10),ts
FROM meters
GROUP BY tbname, location;
分步查询示例
当需要结合其他聚合函数分析时，必须使用分步查询：
-- 第一步：获取 TOP 值
SELECT location,TOP(current, 5) as peak_current,ts
FROM meters
GROUP BY location;-- 第二步：获取统计信息（需要单独查询）
SELECT location,MAX(current) as max_current,AVG(current) as avg_current,COUNT(*) as total_records
FROM meters
GROUP BY location;-- 第三步：在应用层合并分析结果
与 BOTTOM 函数的对比查询
-- 查询峰值数据
SELECT location,TOP(current, 3) as peak_values,ts
FROM meters
GROUP BY location;-- 单独查询谷值数据
SELECT location,BOTTOM(current, 3) as valley_values,ts
FROM meters
GROUP BY location;
注意事项
- 参数限制: k 值取值范围为 [1, 100]
- NULL 值处理: TOP 函数自动忽略 NULL 值
- 相同值处理: 当多条记录有相同值且超出 k 条限制时，会随机选取
- 时间戳返回: 系统会同时返回对应记录的时间戳列
- 排序保证: 返回结果按照值的大小降序排列
- 性能考虑: 在大表上使用时建议配合适当的 WHERE 条件过滤
- FILL 限制: TOP 函数不支持 FILL 子句
- 函数唯一性: 一个 SQL 语句中只能使用一个 TOP 函数
- ORDER BY 限制: TOP 函数不能在 ORDER BY 子句中使用
- 聚合函数混用限制: TOP 函数不能与其他聚合函数（如 MAX、MIN、AVG、SUM、COUNT 等）在同一个 SELECT 语句中使用
- 嵌套限制: TOP 函数不能嵌套在其他聚合函数中
相关函数
- BOTTOM(): 返回最小的 k 个值
- MAX(): 返回最大值（需单独查询）
- MIN(): 返回最小值（需单独查询）
- SAMPLE(): 返回随机采样的 k 个值
- LAST(): 返回最后的非 NULL 值
关于 TDengine
TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。