当前位置： 首页 > news >正文

TDengine 聚合函数 HISTOGRAM 用户手册

news 2025/9/25 18:46:22

在这里插入图片描述

HISTOGRAM 函数用户手册（智能电表场景）

1. 函数概述

HISTOGRAM 是 TDengine 的聚合函数，用于统计数值在指定区间内的分布情况。该函数将数据按照用户定义的区间进行分组统计，返回每个区间内数据的数量，常用于数据分布分析、异常检测、质量评估等场景。在智能电表应用中，可用于分析电压、电流、功率等参数的分布特征。

2. 语法

SELECT HISTOGRAM(expr, bin_type, bin_description, normalized) FROM meters [WHERE condition];

参数说明

  • expr：需要统计分布的数值型字段
  • bin_type：字符串类型，定义分箱类型
    • "USER_INPUT"：自定义分箱
    • "linear_bin"：线性分箱
    • "log_bin"：对数分箱
  • bin_description：字符串类型，定义分箱参数
    • 自定义分箱："[1,3,5,7]" 格式的数组字符串
    • 线性分箱：'{"start":1, "width":3, "count":8, "infinity":true}' 格式的 JSON 字符串
    • 对数分箱：'{"start":1, "factor":2, "count":8, "infinity":true}' 格式的 JSON 字符串
  • normalized：整数，是否归一化，1 表示归一化，0 表示不归一化

3. 返回值

  • 返回 VARCHAR 类型的 JSON 格式字符串
  • 包含各个区间及其对应的统计数量或比例
  • 每行结果格式：{"lower_bin":下界, "upper_bin":上界, "count":数量}

4. 函数计算原理与实际意义

4.1 计算过程详解

自定义分箱（USER_INPUT）
-- 例如：分析电压分布，定义区间 [200, 210, 220, 230, 240]
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,210,220,230,240]', 0) FROM meters;

这会创建以下区间：

  • (200, 210]：低电压区间
  • (210, 220]：正常偏低区间
  • (220, 230]：正常偏高区间
  • (230, 240]：高电压区间
线性分箱（linear_bin）
-- 线性分箱：从200V开始，每10V一个区间，共8个区间
SELECT HISTOGRAM(voltage, 'linear_bin', '{"start":200, "width":10, "count":8, "infinity":false}', 0) FROM meters;

创建区间：(200,210], (210,220], …, (270,280]

对数分箱（log_bin）
-- 对数分箱：从1开始，因子为2，共6个区间
SELECT HISTOGRAM(current, 'log_bin', '{"start":1, "factor":2, "count":6, "infinity":true}', 0) FROM meters;

创建区间：(1,2], (2,4], (4,8], (8,16], (16,32], (32,64], (-∞,1], (64,+∞)

4.2 结果格式示例

-- 查询结果示例
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[210,220,230,240]', 0) FROM meters;

结果格式：

{"lower_bin":210, "upper_bin":220, "count":150}
{"lower_bin":220, "upper_bin":230, "count":300}  
{"lower_bin":230, "upper_bin":240, "count":50}

4.3 实际生产意义的直观理解

电压质量监控示例
-- 监控某区域24小时的电压质量分布
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,210,220,230,240]', 1) AS voltage_quality 
FROM meters 
WHERE location = 'California.SanFrancisco' AND ts >= NOW() - 24h;

结果解读：

{"lower_bin":200, "upper_bin":210, "count":0.05}   // 5% 低压情况
{"lower_bin":210, "upper_bin":220, "count":0.40}   // 40% 正常偏低  
{"lower_bin":220, "upper_bin":230, "count":0.45}   // 45% 正常偏高
{"lower_bin":230, "upper_bin":240, "count":0.10}   // 10% 高压情况

运维决策：

  • 85% 的时间电压正常（210-230V）
  • 10% 的时间存在高压问题，需要调压器介入
  • 5% 的时间存在低压问题，需要检查线路
负荷分布分析示例
-- 分析用电负荷分布模式
SELECT HISTOGRAM(power, 'linear_bin', '{"start":0, "width":2000, "count":6, "infinity":true}', 0) AS load_pattern 
FROM meters 
WHERE ts >= NOW() - 30d;

结果解读：

{"lower_bin":0, "upper_bin":2000, "count":5000}      // 低负荷时段
{"lower_bin":2000, "upper_bin":4000, "count":8000}   // 正常负荷  
{"lower_bin":4000, "upper_bin":6000, "count":4000}   // 中等负荷
{"lower_bin":6000, "upper_bin":8000, "count":2000}   // 高负荷
{"lower_bin":8000, "upper_bin":10000, "count":800}   // 峰值负荷
{"lower_bin":10000, "upper_bin":12000, "count":200}  // 极高负荷

5. 智能电表应用场景

基于智能电表数据库结构：

CREATE TABLE meters (ts TIMESTAMP,voltage FLOAT,current FLOAT,power FLOAT
) TAGS (groupid INT,location VARCHAR(50)
);

5.1 电压分布分析

自定义区间电压分布
-- 分析电压在自定义区间的分布
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,210,220,230,240,250]', 0) AS voltage_distribution 
FROM meters 
WHERE ts >= NOW() - 24h;-- 归一化的电压分布比例
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,210,220,230,240,250]', 1) AS voltage_ratio 
FROM meters 
WHERE ts >= NOW() - 24h;
线性分箱电压分析
-- 电压线性分箱分布（从200V开始，每5V一个区间，共20个区间）
SELECT HISTOGRAM(voltage, 'linear_bin', '{"start":200, "width":5, "count":20, "infinity":true}', 0) AS voltage_linear_dist 
FROM meters 
WHERE location = 'California.SanFrancisco';

5.2 电流负荷分布

电流负荷等级分析
-- 按电流等级分析负荷分布
SELECT HISTOGRAM(current, 'USER_INPUT', '[0,5,10,15,20,25,30]', 0) AS current_load_levels 
FROM meters 
WHERE ts >= NOW() - 7d;-- 各区域电流分布对比
SELECT location,HISTOGRAM(current, 'USER_INPUT', '[0,10,20,30,40,50]', 1) AS current_distribution
FROM meters 
WHERE ts >= NOW() - 30d
GROUP BY location;
对数分箱电流分析
-- 电流对数分箱分布（适合跨度较大的数据）
SELECT HISTOGRAM(current, 'log_bin', '{"start":0.1, "factor":2, "count":10, "infinity":true}', 0) AS current_log_dist 
FROM meters 
WHERE ts >= NOW() - 24h;

5.3 功率消耗模式分析

功率等级分布
-- 功率消耗等级分布分析
SELECT HISTOGRAM(power, 'USER_INPUT', '[0,1000,2000,3000,4000,5000,8000,10000]', 0) AS power_levels 
FROM meters 
WHERE ts >= NOW() - 30d;-- 按设备组分析功率分布
SELECT groupid,HISTOGRAM(power, 'linear_bin', '{"start":0, "width":1000, "count":15, "infinity":true}', 1) AS power_distribution
FROM meters 
WHERE ts >= NOW() - 7d
GROUP BY groupid;

5.4 电网质量评估

电压质量分级
-- 电压质量分级统计（基于国标）
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[0,207,209,231,233,300]', 0) AS voltage_quality_levels 
FROM meters 
WHERE ts >= NOW() - 24h;
-- 区间含义：(0,207]异常低压, (207,209]低压, (209,231]正常, (231,233]高压, (233,300]异常高压
电流稳定性评估
-- 电流稳定性分级
SELECT location,HISTOGRAM(current, 'USER_INPUT', '[0,5,10,15,20,30,50]', 1) AS current_stability_dist
FROM meters 
WHERE ts >= NOW() - 7d
GROUP BY location;

5.5 异常检测分析

异常值分布识别
-- 识别电压异常值的分布情况
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[0,180,200,210,230,240,260,300]', 0) AS abnormal_voltage_dist 
FROM meters 
WHERE (voltage < 210 OR voltage > 240)AND ts >= NOW() - 30d;-- 过载电流分布分析
SELECT HISTOGRAM(current, 'linear_bin', '{"start":30, "width":10, "count":10, "infinity":true}', 0) AS overload_current_dist 
FROM meters 
WHERE current > 30 AND ts >= NOW() - 7d;

5.6 时段对比分析

白天vs夜间功率分布
-- 白天时段功率分布
SELECT HISTOGRAM(power, 'USER_INPUT', '[0,500,1000,2000,3000,5000,8000]', 1) AS daytime_power_dist 
FROM meters 
WHERE ts >= '2024-09-22 06:00:00' AND ts < '2024-09-22 18:00:00';-- 夜间时段功率分布
SELECT HISTOGRAM(power, 'USER_INPUT', '[0,500,1000,2000,3000,5000,8000]', 1) AS nighttime_power_dist 
FROM meters 
WHERE ts >= '2024-09-22 19:00:00' AND ts <= '2024-09-22 23:59:59';

6. 使用注意事项

6.1 参数格式要求

  1. 自定义分箱（USER_INPUT）

    -- 正确格式：数组必须是字符串格式
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[210,220,230,240]', 0) FROM meters;-- 错误格式
SELECT HISTOGRAM(voltage, 'USER_INPUT', [210,220,230,240], 0) FROM meters;  -- 数组不是字符串

  2. 线性分箱（linear_bin）

    -- 正确格式：JSON字符串，包含4个必需字段
SELECT HISTOGRAM(current, 'linear_bin', '{"start":0, "width":5, "count":10, "infinity":true}', 0) FROM meters;-- 错误格式
SELECT HISTOGRAM(current, 'linear_bin', '{"start":0, "width":5, "count":10}', 0) FROM meters;  -- 缺少infinity字段

  3. 对数分箱（log_bin）

    -- 正确格式：JSON字符串，factor必须大于0且不等于1
SELECT HISTOGRAM(power, 'log_bin', '{"start":1, "factor":2, "count":6, "infinity":true}', 0) FROM meters;-- 错误格式
SELECT HISTOGRAM(power, 'log_bin', '{"start":1, "factor":1, "count":6, "infinity":true}', 0) FROM meters;  -- factor不能为1

6.2 数据类型限制

-- ✅ 支持的数据类型：数值类型
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,220,240]', 0) FROM meters;    -- FLOAT
SELECT HISTOGRAM(groupid, 'USER_INPUT', '[1,5,10]', 0) FROM meters;        -- INT标签-- ❌ 不支持的数据类型
SELECT HISTOGRAM(location, 'USER_INPUT', '[a,b,c]', 0) FROM meters;        -- 字符串类型
SELECT HISTOGRAM(ts, 'USER_INPUT', '[1,2,3]', 0) FROM meters;             -- 时间戳类型

6.3 性能优化建议

-- 推荐：限制时间范围和数据量
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,220,240]', 0) FROM meters 
WHERE ts >= NOW() - 24h AND location = 'California.SanFrancisco';-- 推荐：合理设置分箱数量（建议5-20个区间）
SELECT HISTOGRAM(current, 'linear_bin', '{"start":0, "width":10, "count":8, "infinity":true}', 1) FROM meters;-- 避免：过多的分箱数量
SELECT HISTOGRAM(voltage, 'linear_bin', '{"start":200, "width":1, "count":100, "infinity":false}', 0) FROM meters;

6.4 结果解析

-- 测试用例中的实际结果格式
SELECT HISTOGRAM(c_int, 'USER_INPUT', '[0,3,6,9]', 0) FROM meters WHERE c_int < 10;

返回结果：

{"lower_bin":0, "upper_bin":3, "count":0}
{"lower_bin":3, "upper_bin":6, "count":0}  
{"lower_bin":6, "upper_bin":9, "count":1}

每行代表一个区间的统计结果，包含下界、上界和计数。

7. 常见错误及解决方案

7.1 参数数量错误

-- ❌ 错误：参数不足
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,220,240]') FROM meters;-- ✅ 正确：必须提供4个参数  
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[200,220,240]', 0) FROM meters;

运行结果：
在这里插入图片描述

7.2 JSON格式错误

-- ❌ 错误：JSON格式不正确
SELECT HISTOGRAM(current, 'linear_bin', '{start:0, width:5}', 0) FROM meters;-- ✅ 正确：标准JSON格式
SELECT HISTOGRAM(current, 'linear_bin', '{"start":0, "width":5, "count":10, "infinity":false}', 0) FROM meters;

运行结果：
在这里插入图片描述

7.3 数组顺序错误

-- ❌ 错误：数组元素不是递增序列
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[220,210,230,240]', 0) FROM meters;-- ✅ 正确：数组必须递增
SELECT HISTOGRAM(voltage, 'USER_INPUT', '[210,220,230,240]', 0) FROM meters;

8. 总结

HISTOGRAM 函数是智能电表数据分析中的强大工具，能够：

  1. 分布分析：清晰展示电压、电流、功率等参数在各个区间的分布情况
  2. 质量评估：基于分布特征评估电网质量和设备性能
  3. 异常检测：通过分布异常快速识别系统故障
  4. 趋势分析：对比不同时段、区域的分布差异

关键使用要点：

  • 严格按照4参数格式：HISTOGRAM(字段, 分箱类型, 分箱描述, 归一化标志)
  • 分箱描述必须是正确格式的字符串
  • 合理选择分箱策略和区间数量
  • 注意性能优化，避免大数据集无条件查询

通过正确使用 HISTOGRAM 函数，可以为智能电表系统的监控分析提供重要的统计洞察，助力电网安全高效运行。

关于 TDengine

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

http://www.dtcms.com/a/404331.html

相关文章：

  • 网站建设专题的意义软装设计师培训机构
  • 怎么做返利网站吗郑州短视频拍摄制作公司
  • 广州市从化区住房和建设局网站品牌形象设计方案
  • 郑州网站建设国奥大厦ui网页设计规则
  • 云企网站seo页面优化技术
  • 福州正规网站建设公司报价网盘 wordpress模板
  • 网络营销成功的案例及其原因郴州网站seo外包
  • 现在流行做网站吗wordpress添加加载中
  • git报错：Unlink of file ‘‘ failed. Should I try again? (y/n)
  • 未来中森网站建设公司有合作社做网站得不
  • 网站优化 英文网页更改
  • 做办公设备网站网站建设标新立异
  • 专业营销网站网站建设作品
  • 13 【C++】C++的类型转换
  • STM32定时器（寄存器与HAL库实现）
  • 教学资源库网站建设立项申报书网络维护员岗位职责
  • 第10节-CTE公用表表达式-Recursive-CTE
  • 广东省备案网站建设方案书iis发布网站的教程
  • git基础操作
  • 茂名专业网站建设外贸出口流程12步骤图
  • 响应式网站 模版58同城企业网站怎么做的
  • ARM——中断（按键）
  • 【conda配环境】导出环境配置与安装
  • 上饶市建设厅网站快速达建网站
  • 深圳做h5网站公司wordpress 入口
  • 网站建设一般多钱高职院校优质校建设专栏网站
  • 网站建设属于哪种公司科技公司logo
  • 个人网站备案入口注册网站建设公司
  • 网站建设要求报告网上做网站网站代理赚钱吗
  • 网站的角色设置如何做北京建站免费模板