TDengine 的 HISTOGRAM() 函数用户手册

HISTOGRAM 函数用户使用手册

概述

HISTOGRAM 函数是 TDengine 中的一个聚合函数，用于对数值数据进行直方图统计分析。它将数据按照指定的区间（bins）进行分组统计，返回每个区间内数据的数量分布，帮助用户理解数据的分布特征。

语法

HISTOGRAM(expr, bin_type, bin_desc, normalized)

参数说明

返回值类型

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：每个区间的宽度，不能为0
• count：要生成的区间数量，范围 [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：第一个区间的起始值，不能为0
• factor：倍数因子，必须大于0且不等于1
• count：要生成的区间数量，范围 [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';

解决的问题

使用限制

适用范围

• 表类型：支持普通表和超级表
• 嵌套查询：支持内层查询和外层查询
• 版本要求：TDengine 3.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;

注意事项