TDengine函数大全-聚合函数

以下内容来自 TDengine 官方文档及
GitHub 内容。

以下所有示例基于 TDengine 3.1.0.3

TDengine函数大全

1.数学函数
2.字符串函数
3.转换函数
4.时间和日期函数
5.聚合函数
6.选择函数
7.时序数据库特有函数
8.系统函数

聚合函数

- TDengine函数大全
- - APERCENTILE
  - AVG
  - COUNT
  - ELAPSED
  - LEASTSQUARES
  - SPREAD
  - STDDEV
  - SUM
  - HYPERLOGLOG
  - HISTOGRAM
  - PERCENTILE

APERCENTILE

APERCENTILE(expr, p [, algo_type])algo_type: {"default"| "t-digest"
}

功能说明：统计表/超级表中指定列的值的近似百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。

返回数据类型： DOUBLE。

适用数据类型：数值类型。

适用于：表和超级表。

说明：

p值范围是[0,100]，当为0时等同于MIN，为100时等同于MAX。
algo_type 取值为 “default” 或 “t-digest”。输入为 “default” 时函数使用基于直方图算法进行计算。输入为 “t-digest” 时使用t-digest算法计算分位数的近似结果。如果不指定 algo_type 则使用 “default” 算法。
"t-digest"算法的近似结果对于输入数据顺序敏感，对超级表查询时不同的输入排序结果可能会有微小的误差。

示例:

> select * from t6;ts            |     v1      |
========================================2023-08-31 09:46:31.582 |           1 |2023-08-31 09:46:33.366 |           2 |2023-08-31 09:46:35.271 |           3 |2023-08-31 09:46:37.699 |           4 |2023-08-31 09:46:39.562 |           5 |2023-08-31 09:46:41.868 |           6 |2023-08-31 09:46:44.229 |           7 |2023-08-31 09:46:46.365 |           8 |2023-08-31 09:46:48.345 |           9 |2023-08-31 09:46:50.451 |          10 |> select apercentile(v1,10) from t6;apercentile(v1,10)     |
============================1.000000000000000 |> select apercentile(v1,20) from t6;apercentile(v1,20)     |
============================2.000000000000000 |> select apercentile(v1,90) from t6;apercentile(v1,90)     |
============================9.000000000000000 |> select apercentile(v1,90,"t-digest") from t6;apercentile(v1,90,"t-digest") |
================================9.500000000000000e+00 |

AVG

AVG(expr)

功能说明：统计指定字段的平均值。

返回数据类型：DOUBLE。

适用数据类型：数值类型。

适用于：表和超级表。

示例:

> select * from t6;ts            |     v1      |
========================================2023-08-31 09:46:31.582 |           1 |2023-08-31 09:46:33.366 |           2 |2023-08-31 09:46:35.271 |           3 |2023-08-31 09:46:37.699 |           4 |2023-08-31 09:46:39.562 |           5 |2023-08-31 09:46:41.868 |           6 |2023-08-31 09:46:44.229 |           7 |2023-08-31 09:46:46.365 |           8 |2023-08-31 09:46:48.345 |           9 |2023-08-31 09:46:50.451 |          10 |> select avg(v1) from t6;avg(v1)          |
============================5.500000000000000 |

COUNT

COUNT({* | expr})

功能说明：统计指定字段的记录行数。

返回数据类型：BIGINT。

适用数据类型：全部类型字段。

适用于：表和超级表。

使用说明:

可以使用星号(*)来替代具体的字段，使用星号(*)返回全部记录数量。
如果统计字段是具体的列，则返回该列中非 NULL 值的记录数量。

示例:

> select * from t6;ts            |     v1      |
========================================2023-08-31 09:46:31.582 |           1 |2023-08-31 09:46:33.366 |           2 |2023-08-31 09:46:35.271 |           3 |2023-08-31 09:46:37.699 |           4 |2023-08-31 09:46:39.562 |           5 |2023-08-31 09:46:41.868 |           6 |2023-08-31 09:46:44.229 |           7 |2023-08-31 09:46:46.365 |           8 |2023-08-31 09:46:48.345 |           9 |2023-08-31 09:46:50.451 |          10 |> select count(*) from t6;count(*)        |
========================10 |> select count(v1) from t6;count(v1)       |
========================10 |> select count(*) from (select count(v1) from t6);count(*)        |
========================1 |

ELAPSED

ELAPSED(ts_primary_key [, time_unit])

功能说明：elapsed函数表达了统计周期内连续的时间长度，和twa函数配合使用可以计算统计曲线下的面积。在通过INTERVAL子句指定窗口的情况下，统计在给定时间范围内的每个窗口内有数据覆盖的时间范围；如果没有INTERVAL子句，则返回整个给定时间范围内的有数据覆盖的时间范围。注意，ELAPSED返回的并不是时间范围的绝对值，而是绝对值除以time_unit所得到的单位个数。

返回结果类型：DOUBLE。

适用数据类型：TIMESTAMP。

适用于: 表，超级表，嵌套查询的外层查询

说明：

ts_primary_key参数只能是表的第一列，即 TIMESTAMP 类型的主键列。
按time_unit参数指定的时间单位返回，最小是数据库的时间分辨率。time_unit 参数未指定时，以数据库的时间分辨率为时间单位。支持的时间单位 time_unit 如下：
1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。
可以和interval组合使用，返回每个时间窗口的时间戳差值。需要特别注意的是，除第一个时间窗口和最后一个时间窗口外，中间窗口的时间戳差值均为窗口长度。
order by asc/desc不影响差值的计算结果。
对于超级表，需要和group by tbname子句组合使用，不可以直接使用。
对于普通表，不支持和group by子句组合使用。
对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。
不支持与leastsquares、diff、derivative、top、bottom、last_row、interp等函数混合使用。

示例:

> select * from t6;ts            |     v1      |
========================================2023-08-31 09:46:31.582 |           1 |2023-08-31 09:46:33.366 |           2 |2023-08-31 09:46:35.271 |           3 |2023-08-31 09:46:37.699 |           4 |2023-08-31 09:46:39.562 |           5 |2023-08-31 09:46:41.868 |           6 |2023-08-31 09:46:44.229 |           7 |2023-08-31 09:46:46.365 |           8 |2023-08-31 09:46:48.345 |           9 |2023-08-31 09:46:50.451 |          10 |> select elapsed(ts) from t6;elapsed(ts)        |
============================18869.000000000000000 |> select elapsed(ts,1s) from t6;elapsed(ts,1s)       |
============================18.869000000000000 |> select elapsed(ts,1m) from t6;elapsed(ts,1m)       |
============================0.314483333333333 |> select elapsed(ts,1h) from t6;elapsed(ts,1h)       |
============================0.005241388888889 |> select elapsed(ts,1u) from t6;DB error: ELAPSED function time unit parameter should be greater than db precision (0.000691s)> select _wstart,_wend,elapsed(ts,1a) from t6 interval(1s);_wstart         |          _wend          |      elapsed(ts,1a)       |
================================================================================2023-08-31 09:46:31.000 | 2023-08-31 09:46:32.000 |       418.000000000000000 |2023-08-31 09:46:33.000 | 2023-08-31 09:46:34.000 |      1000.000000000000000 |2023-08-31 09:46:35.000 | 2023-08-31 09:46:36.000 |      1000.000000000000000 |2023-08-31 09:46:37.000 | 2023-08-31 09:46:38.000 |      1000.000000000000000 |2023-08-31 09:46:39.000 | 2023-08-31 09:46:40.000 |      1000.000000000000000 |2023-08-31 09:46:41.000 | 2023-08-31 09:46:42.000 |      1000.000000000000000 |2023-08-31 09:46:44.000 | 2023-08-31 09:46:45.000 |      1000.000000000000000 |2023-08-31 09:46:46.000 | 2023-08-31 09:46:47.000 |      1000.000000000000000 |2023-08-31 09:46:48.000 | 2023-08-31 09:46:49.000 |      1000.000000000000000 |2023-08-31 09:46:50.000 | 2023-08-31 09:46:51.000 |       451.000000000000000 |

LEASTSQUARES

LEASTSQUARES(expr, start_val, step_val)

功能说明：统计表中某列的值是主键（时间戳）的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。

返回数据类型：字符串表达式（斜率, 截距）。

适用数据类型：expr 必须是数值类型。

适用于：表。

示例:

> select * from t7;ts            |     v1      |
========================================2023-08-01 01:01:01.000 |           1 |2023-08-01 01:01:02.000 |           2 |2023-08-01 01:01:03.000 |           3 |2023-08-01 01:01:04.000 |           4 |2023-08-01 01:01:05.000 |           5 |2023-08-01 01:01:06.000 |           6 |2023-08-01 01:01:07.000 |           7 |2023-08-01 01:01:08.000 |           8 |2023-08-01 01:01:09.000 |           9 |> select leastsquares(v1,0,1) from t7;leastsquares(v1,0,1)           |
==========================================={slop:1.000000, intercept:1.000000}      |> select leastsquares(v1,0,2) from t7;leastsquares(v1,0,2)           |
==========================================={slop:0.500000, intercept:1.000000}      |> select leastsquares(v1,0,5) from t7;leastsquares(v1,0,5)           |
==========================================={slop:0.200000, intercept:1.000000}      |

SPREAD

SPREAD(expr)

功能说明：统计表中某列的最大值和最小值之差。

返回数据类型：DOUBLE。

适用数据类型：INTEGER, TIMESTAMP。

适用于：表和超级表。

示例:

select * from t7;ts            |     v1      |
========================================2023-08-01 01:01:01.000 |           1 |2023-08-01 01:01:02.000 |           2 |2023-08-01 01:01:03.000 |           3 |2023-08-01 01:01:04.000 |           4 |2023-08-01 01:01:05.000 |           5 |2023-08-01 01:01:06.000 |           6 |2023-08-01 01:01:07.000 |           7 |2023-08-01 01:01:08.000 |           8 |2023-08-01 01:01:09.000 |           9 |> select spread(ts),spread(v1) from t7;spread(ts)         |        spread(v1)         |
========================================================8000.000000000000000 |         8.000000000000000 |

STDDEV

STDDEV(expr)

功能说明：统计表中某列的均方差。

返回数据类型：DOUBLE。

适用数据类型：数值类型。

适用于：表和超级表。

示例:

> select * from t7;ts            |     v1      |
========================================2023-08-01 01:01:01.000 |           1 |2023-08-01 01:01:02.000 |           2 |2023-08-01 01:01:03.000 |           3 |2023-08-01 01:01:04.000 |           4 |2023-08-01 01:01:05.000 |           5 |2023-08-01 01:01:06.000 |           6 |2023-08-01 01:01:07.000 |           7 |2023-08-01 01:01:08.000 |           8 |2023-08-01 01:01:09.000 |           9 |> select stddev(v1) from t7;stddev(v1)         |
============================2.581988897471612 |

SUM

SUM(expr)

功能说明：统计表/超级表中某列的和。

返回数据类型：DOUBLE, BIGINT。

适用数据类型：数值类型。

适用于：表和超级表。

示例:

> select * from t7;ts            |     v1      |
========================================2023-08-01 01:01:01.000 |           1 |2023-08-01 01:01:02.000 |           2 |2023-08-01 01:01:03.000 |           3 |2023-08-01 01:01:04.000 |           4 |2023-08-01 01:01:05.000 |           5 |2023-08-01 01:01:06.000 |           6 |2023-08-01 01:01:07.000 |           7 |2023-08-01 01:01:08.000 |           8 |2023-08-01 01:01:09.000 |           9 |> select sum(v1) from t7;sum(v1)        |
========================45 |

HYPERLOGLOG

HYPERLOGLOG(expr)

功能说明：

采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。
在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。

返回结果类型：INTEGER。

适用数据类型：任何类型。

适用于：表和超级表。

示例:

> select count(*) from meters;count(*)        |
========================109847142 |> select hyperloglog(current) from meters;hyperloglog(current)  |
========================1003 |> select count(*) from (select unique(current) from meters);count(*)        |
========================1009 |> select hyperloglog(voltage) from meters;hyperloglog(voltage)  |
========================1001 |> select count(*) from (select unique(voltage) from meters);count(*)        |
========================1000 |

HISTOGRAM

HISTOGRAM(expr，bin_type, bin_description, normalized)

功能说明：统计数据按照用户指定区间的分布。

返回结果类型：如归一化参数 normalized 设置为 1，返回结果为 DOUBLE 类型，否则为 BIGINT 类型。

适用数据类型：数值型字段。

适用于: 表和超级表。

详细说明：

bin_type 用户指定的分桶类型, 有效输入类型为"user_input“, ”linear_bin", “log_bin”。
bin_description 描述如何生成分桶区间，针对三种桶类型，分别为以下描述格式(均为 JSON 格式字符串)：
- “user_input”: “[1, 3, 5, 7]”
  用户指定 bin 的具体数值。
- “linear_bin”: “{“start”: 0.0, “width”: 5.0, “count”: 5, “infinity”: true}”
  “start” 表示数据起始点，“width” 表示每次 bin 偏移量, “count” 为 bin 的总数，“infinity” 表示是否添加（-inf, inf）作为区间起点和终点，
  生成区间为[-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]。
- “log_bin”: “{“start”:1.0, “factor”: 2.0, “count”: 5, “infinity”: true}”
  “start” 表示数据起始点，“factor” 表示按指数递增的因子，“count” 为 bin 的总数，“infinity” 表示是否添加（-inf, inf）作为区间起点和终点，
  生成区间为[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]。
normalized 是否将返回结果归一化到 0~1 之间。有效输入为 0 和 1。

示例:

PERCENTILE

PERCENTILE(expr, p [, p1] ... )

功能说明：统计表中某列的值百分比分位数。

返回数据类型：该函数最小参数个数为 2 个，最大参数个数为 11 个。可以最多同时返回 10 个百分比分位数。当参数个数为 2 时，返回一个分位数，类型为DOUBLE，当参数个数大于 2 时，返回类型为VARCHAR, 格式为包含多个返回值的JSON数组。

应用字段：数值类型。

适用于：表。

使用说明：

P值取值范围 0≤P≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX;
同时计算针对同一列的多个分位数时，建议使用一个PERCENTILE函数和多个参数的方式，能很大程度上降低查询的响应时间。
比如，使用查询SELECT percentile(col, 90, 95, 99) FROM table, 性能会优于SELECT percentile(col, 90), percentile(col, 95), percentile(col, 99) from table。

示例:

> select * from t7;ts            |     v1      |
========================================2023-08-01 01:01:01.000 |           1 |2023-08-01 01:01:02.000 |           2 |2023-08-01 01:01:03.000 |           3 |2023-08-01 01:01:04.000 |           4 |2023-08-01 01:01:05.000 |           5 |2023-08-01 01:01:06.000 |           6 |2023-08-01 01:01:07.000 |           7 |2023-08-01 01:01:08.000 |           8 |2023-08-01 01:01:09.000 |           9 |2023-08-01 01:01:10.000 |          10 |> select percentile(v1,10,20,50,80) from t7;percentile(v1,10,20,50,80)        |
===========================================[1.900000, 2.800000, 5.500000, 8.200000] |