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;

注意事项

1. 参数限制: k 值取值范围为 [1, 100]
2. NULL 值处理: TOP 函数自动忽略 NULL 值
3. 相同值处理: 当多条记录有相同值且超出 k 条限制时，会随机选取
4. 时间戳返回: 系统会同时返回对应记录的时间戳列
5. 排序保证: 返回结果按照值的大小降序排列
6. 性能考虑: 在大表上使用时建议配合适当的 WHERE 条件过滤
7. FILL 限制: TOP 函数不支持 FILL 子句
8. 函数唯一性: 一个 SQL 语句中只能使用一个 TOP 函数
9. ORDER BY 限制: TOP 函数不能在 ORDER BY 子句中使用
10. 聚合函数混用限制: TOP 函数不能与其他聚合函数（如 MAX、MIN、AVG、SUM、COUNT 等）在同一个 SELECT 语句中使用
11. 嵌套限制: TOP 函数不能嵌套在其他聚合函数中

相关函数

• BOTTOM(): 返回最小的 k 个值
• MAX(): 返回最大值（需单独查询）
• MIN(): 返回最小值（需单独查询）
• SAMPLE(): 返回随机采样的 k 个值
• LAST(): 返回最后的非 NULL 值

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。