TDengine 的 HISTOGRAM() 函数用户手册
HISTOGRAM 函数用户使用手册
概述
HISTOGRAM 函数是 TDengine 中的一个聚合函数，用于对数值数据进行直方图统计分析。它将数据按照指定的区间（bins）进行分组统计，返回每个区间内数据的数量分布，帮助用户理解数据的分布特征。
语法
HISTOGRAM(expr, bin_type, bin_desc, normalized)
参数说明
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
expr | 数值类型 | 是 | 要进行直方图分析的字段或表达式，支持所有数值类型（整型、浮点型、无符号整型等） |
bin_type | STRING | 是 | 分箱类型，支持三种类型： - 'user_input'：用户自定义分箱- 'linear_bin'：线性等距分箱- 'log_bin'：对数分箱 |
bin_desc | STRING | 是 | 分箱描述，格式依据 bin_type 而定，详见下文 |
normalized | INT | 是 | 标准化标志，取值为 0 或 1： - 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时，会自动添加边界区间处理极值