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：每个区间的宽度，不能为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';

解决的问题

1. 数据分布可视化：将连续数值数据离散化，便于理解数据分布特征
2. 统计分析支持：为后续的统计分析和机器学习提供数据预处理
3. 异常值识别：通过分布分析快速定位异常数据
4. 性能监控：实时监控系统性能指标的分布变化
5. 业务洞察：通过数据分布分析获得业务洞察

使用限制

1. 参数限制：

   • count 参数范围：[1, 1000]
   • factor 必须大于0且不等于1
   • width 不能为0
   • 对数分箱的 start 不能为0

2. 数据类型限制：

   • expr 必须是数值类型
   • 不支持字符串、布尔值、时间戳类型

3. 函数组合限制：

   • 不能与其他聚合函数嵌套使用
   • 不能在 WHERE、GROUP BY、PARTITION BY 子句中使用其他聚合函数

适用范围

• 表类型：支持普通表和超级表
• 嵌套查询：支持内层查询和外层查询
• 版本要求：TDengine 3.0+

最佳实践

1. 选择合适的分箱类型：

   • 均匀分布数据：使用 linear_bin
   • 指数分布数据：使用 log_bin
   • 特定业务需求：使用 user_input

2. 合理设置区间数量：

   • 一般建议10-50个区间
   • 数据量大时可适当增加区间数

3. 标准化的使用：

   • 比较不同数据集时使用 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;

注意事项

1. 返回结果按区间顺序排列
2. 区间采用左开右闭原则：(lower, upper]
3. NULL 值会被自动忽略
4. 当 normalized=1 时，所有区间的 count 值总和为1（除非所有数据都为NULL）
5. 使用 infinity=true 时，会自动添加边界区间处理极值