TDengine 聚合函数 HISTOGRAM 用户手册

TDengine （老段）2025-09-25 14:21

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

1. 函数概述

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

2. 语法

sql 复制代码 
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）
sql 复制代码 
-- 例如：分析电压分布，定义区间 [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）
sql 复制代码 
-- 线性分箱：从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）
sql 复制代码 
-- 对数分箱：从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 结果格式示例

sql 复制代码 
-- 查询结果示例
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 实际生产意义的直观理解

电压质量监控示例
sql 复制代码 
-- 监控某区域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% 的时间存在低压问题，需要检查线路
负荷分布分析示例
sql 复制代码 
-- 分析用电负荷分布模式
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. 智能电表应用场景

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

sql 复制代码 
CREATE TABLE meters (
    ts TIMESTAMP,
    voltage FLOAT,
    current FLOAT,
    power FLOAT
) TAGS (
    groupid INT,
    location VARCHAR(50)
);

5.1 电压分布分析

自定义区间电压分布
sql 复制代码 
-- 分析电压在自定义区间的分布
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;
线性分箱电压分析
sql 复制代码 
-- 电压线性分箱分布（从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 电流负荷分布

电流负荷等级分析
sql 复制代码 
-- 按电流等级分析负荷分布
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;
对数分箱电流分析
sql 复制代码 
-- 电流对数分箱分布（适合跨度较大的数据）
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 功率消耗模式分析

功率等级分布
sql 复制代码 
-- 功率消耗等级分布分析
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 电网质量评估

电压质量分级
sql 复制代码 
-- 电压质量分级统计（基于国标）
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]异常高压
电流稳定性评估
sql 复制代码 
-- 电流稳定性分级
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 异常检测分析

异常值分布识别
sql 复制代码 
-- 识别电压异常值的分布情况
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夜间功率分布
sql 复制代码 
-- 白天时段功率分布
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）

    sql 复制代码 
    -- 正确格式：数组必须是字符串格式
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）

    sql 复制代码 
    -- 正确格式：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）

    sql 复制代码 
    -- 正确格式：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 数据类型限制

sql 复制代码 
-- ✅ 支持的数据类型：数值类型
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 性能优化建议

sql 复制代码 
-- 推荐：限制时间范围和数据量
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 结果解析

sql 复制代码 
-- 测试用例中的实际结果格式
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 参数数量错误

sql 复制代码 
-- ❌ 错误：参数不足
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格式错误

sql 复制代码 
-- ❌ 错误：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 数组顺序错误

sql 复制代码 
-- ❌ 错误：数组元素不是递增序列
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 提供实时分析、可视化、事件管理与报警等功能。

相关推荐
DokiDoki之父2 小时前
JDBC入门
java·sql·mysql
寻星探路2 小时前
数据库造神计划第十八天---事务（1）
数据库
BullSmall3 小时前
Doris数据库-初识
数据库·doris
Aloudata技术团队3 小时前
智能问数 Agent 如何确保 SQL 生成 100% 准确？
大数据·数据分析·数据可视化
Lx3523 小时前
Hadoop多租户环境下的资源隔离与性能优化
大数据·hadoop
麦聪聊数据3 小时前
企业级数据库管理实战（七）：SQL 到 API，让数据库成为团队的数据服务
数据库·sql·低代码·数据服务
一 乐3 小时前
智慧外贸平台|基于Java+vue的智慧外贸平台系统(源码+数据库+文档)
java·数据库·vue.js·spring boot·论文·毕设·外贸服务系统
阿里云云原生3 小时前
函数计算进化之路：AI 应用运行时的状态剖析
大数据·人工智能·serverless·函数计算
热门推荐
01UV 工具安装与国内镜像源配置指南02GitHub 镜像站点03Spec-Kit 使用指南04UV安装并设置国内源0546个Nano-banana 精选提示词，持续更新中062025年华为杯研赛数学建模竞赛C题完整参考论文 （含模型、MATLAB和Python代码）07保姆级教程：手把手教你用Dify实现完美多轮对话（附Chatflow和提示词）08KGG转MP3工具|非KGM文件|解密音频09Linux下V2Ray安装配置指南10jdk21下载、安装（Windows、Linux、macOS）