TDengine 的 HISTOGRAM() 函数用户手册
HISTOGRAM 函数用户使用手册
概述
HISTOGRAM 函数是 TDengine 中的一个聚合函数，用于对数值数据进行直方图统计分析。它将数据按照指定的区间（bins）进行分组统计，返回每个区间内数据的数量分布，帮助用户理解数据的分布特征。
语法
HISTOGRAM(expr, bin_type, bin_desc, normalized)参数说明
exprbin_type-
\'user_input\'：用户自定义分箱-
\'linear_bin\'：线性等距分箱-
\'log_bin\'：对数分箱bin_descbin_type 而定，详见下文normalized-
0：返回绝对计数-
1：返回归一化百分比（总和为1）返回值类型
STRING - 返回 JSON 格式的字符串，包含每个区间的统计信息。
分箱类型详解
1. 用户自定义分箱 (user_input)
用户直接指定分箱边界点。
bin_desc 格式：
[边界点1, 边界点2, 边界点3, ...]要求：
- 边界点必须是数值类型
- 边界点必须严格递增
- 至少包含2个边界点
- 生成的区间数量 = 边界点数量 - 1
示例：
-- 将数据分为3个区间：(0,3]、(3,6]、(6,9]SELECT HISTOGRAM(c_int, \'user_input\', \'[0,3,6,9]\', 0) FROM table_name;2. 线性等距分箱 (linear_bin)
按照线性等距方式自动生成分箱。
bin_desc 格式：
{ \"start\": 起始值, \"width\": 区间宽度, \"count\": 区间数量, \"infinity\": 是否包含无穷区间}参数说明：
start：第一个区间的起始值width：每个区间的宽度，不能为0count：要生成的区间数量，范围 [1, 1000]infinity：布尔值，true时会在两端添加 (-∞, start] 和 (last, +∞) 区间
示例：
-- 生成5个区间：(-∞,0]、(0,10]、(10,20]、(20,30]、(30,40]、(40,+∞)SELECT HISTOGRAM(c_int, \'linear_bin\', \'{\"start\": 0, \"width\": 10, \"count\": 4, \"infinity\": true}\', 1) FROM table_name;3. 对数分箱 (log_bin)
按照对数比例生成分箱，适用于具有指数分布特征的数据。
bin_desc 格式：
{ \"start\": 起始值, \"factor\": 倍数因子, \"count\": 区间数量, \"infinity\": 是否包含无穷区间}参数说明：
start：第一个区间的起始值，不能为0factor：倍数因子，必须大于0且不等于1count：要生成的区间数量，范围 [1, 1000]infinity：布尔值，控制是否添加无穷区间
生成规则：第 i 个边界点 = start × factor^i
示例：
-- 生成对数分箱：(1,2]、(2,8]、(8,32]、(32,128]SELECT HISTOGRAM(c_float, \'log_bin\', \'{\"start\": 1, \"factor\": 4, \"count\": 4, \"infinity\": false}\', 0) FROM table_name;输出格式
函数返回 JSON 格式的字符串数组，每个元素包含：
{ \"lower_bin\": 区间下界, \"upper_bin\": 区间上界, \"count\": 该区间内的数据量(normalized=0时)或百分比(normalized=1时)}使用场景
1. 数据分布分析
分析数据的分布特征，识别数据的集中趋势和离散程度。
-- 分析温度数据的分布SELECT HISTOGRAM(temperature, \'linear_bin\', \'{\"start\": -10, \"width\": 5, \"count\": 20, \"infinity\": true}\', 1) FROM sensor_data WHERE ts >= \'2024-01-01\' AND ts < \'2024-02-01\';2. 异常检测
通过直方图识别数据中的异常值或异常模式。
-- 检测响应时间的异常分布SELECT HISTOGRAM(response_time, \'log_bin\', \'{\"start\": 1, \"factor\": 2, \"count\": 10, \"infinity\": true}\', 0) FROM api_logs WHERE ts >= NOW() - INTERVAL 1 DAY;3. 性能分析
分析系统性能指标的分布情况，如响应时间、CPU使用率等。
-- 分析CPU使用率分布SELECT HISTOGRAM(cpu_usage, \'user_input\', \'[0,20,40,60,80,100]\', 1) FROM system_metrics WHERE ts >= NOW() - INTERVAL 1 HOUR;4. 业务指标分析
对业务数据进行统计分析，如订单金额分布、用户年龄分布等。
-- 分析订单金额分布SELECT HISTOGRAM(order_amount, \'linear_bin\', \'{\"start\": 0, \"width\": 100, \"count\": 50, \"infinity\": false}\', 1) FROM orders WHERE order_date >= \'2024-01-01\';解决的问题
- 数据分布可视化：将连续数值数据离散化，便于理解数据分布特征
- 统计分析支持：为后续的统计分析和机器学习提供数据预处理
- 异常值识别：通过分布分析快速定位异常数据
- 性能监控：实时监控系统性能指标的分布变化
- 业务洞察：通过数据分布分析获得业务洞察
使用限制
-
参数限制：
count参数范围：[1, 1000]factor必须大于0且不等于1width不能为0- 对数分箱的
start不能为0
-
数据类型限制：
expr必须是数值类型- 不支持字符串、布尔值、时间戳类型
-
函数组合限制：
- 不能与其他聚合函数嵌套使用
- 不能在 WHERE、GROUP BY、PARTITION BY 子句中使用其他聚合函数
适用范围
- 表类型：支持普通表和超级表
- 嵌套查询：支持内层查询和外层查询
- 版本要求：TDengine 3.0+
最佳实践
-
选择合适的分箱类型：
- 均匀分布数据：使用
linear_bin - 指数分布数据：使用
log_bin - 特定业务需求：使用
user_input
- 均匀分布数据：使用
-
合理设置区间数量：
- 一般建议10-50个区间
- 数据量大时可适当增加区间数
-
标准化的使用：
- 比较不同数据集时使用
normalized=1 - 关注绝对数量时使用
normalized=0
- 比较不同数据集时使用
示例应用
-- 示例1：用户自定义分箱分析温度分布SELECT HISTOGRAM(temperature, \'user_input\', \'[-10,0,10,20,30,40]\', 1) FROM weather_data WHERE city=\'Beijing\' AND date >= \'2024-01-01\';-- 示例2：线性分箱分析订单金额SELECT HISTOGRAM(amount, \'linear_bin\', \'{\"start\": 0, \"width\": 50, \"count\": 20, \"infinity\": true}\', 0) FROM orders WHERE created_time >= NOW() - INTERVAL 7 DAY;-- 示例3：对数分箱分析响应时间SELECT HISTOGRAM(latency_ms, \'log_bin\', \'{\"start\": 1, \"factor\": 2, \"count\": 15, \"infinity\": true}\', 1) FROM api_requests WHERE endpoint=\'/api/data\' AND ts >= NOW() - INTERVAL 1 DAY;注意事项
- 返回结果按区间顺序排列
- 区间采用左开右闭原则：(lower, upper]
- NULL 值会被自动忽略
- 当
normalized=1时，所有区间的 count 值总和为1（除非所有数据都为NULL） - 使用
infinity=true时，会自动添加边界区间处理极值
