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 提供实时分析、可视化、事件管理与报警等功能。

相关推荐
ifenxi爱分析28 分钟前
爱分析最新报告解读：AI数据基础设施与数据中台的区别
大数据·人工智能
oradh1 小时前
Oracle XTTS实现跨版本迁移和升级（Oracle 11g单库升级至19C RAC集群）
数据库·oracle·11g升级19c·xtts跨版本迁移和升级
品牌全球行1 小时前
共商共建共享 链接数字未来——“一带一路数字新城（深圳）会客厅筹备办”揭牌仪式在深圳隆重举行
大数据·人工智能
z123456789862 小时前
2026最新两款AI编程工具深度对比实测
java·数据库·ai编程
程序猿DD2 小时前
一个 API Key，统一调用大模型、生图和联网搜索
数据库·网关
YCOSA20252 小时前
雨晨 Windows 11 IOT 企业版 LTSC 24H2 轻装 2合1 26100.8968
windows·物联网
TlSfoward3 小时前
抓包代理链路下的 TLS 指纹变化分析 TLSFOWARD抓包工具
数据库·爬虫·网络协议·搜索引擎·php
乐鑫科技 Espressif3 小时前
用 AI 开发 Zephyr-IoT 应用
人工智能·物联网·esp32·乐鑫科技·zephyr
数智化管理手记3 小时前
账龄分析手工统计易遗漏？自动账龄分析工具怎么搭建
大数据·网络·数据库·人工智能·数据挖掘
LabVIEW开发3 小时前
NI Package Manager安装LabVIEW时InternalServerError错误
网络·数据库·labview·labview知识·labview功能·labview程序
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03如何新建文件夹？ 电脑新建文件夹的4种方法04AI科技热点日报 | 2026年07月01日05幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南06国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路092026 年 AI 大模型 & AI 编程工具实战全总结10Kimi K3 真实体验：全网评价整理，优缺点一次性说清楚