函数
单行函数
单行函数为查询结果中的每一行返回一个结果行。
数学函数
ABS
ABS(expr)
功能说明:获得指定字段的绝对值。
返回结果类型:与指定字段的原始数据类型一致。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
ACOS
ACOS(expr)
功能说明:获得指定字段的反余弦结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
ASIN
ASIN(expr)
功能说明:获得指定字段的反正弦结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
ATAN
ATAN(expr)
功能说明:获得指定字段的反正切结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
CEIL
CEIL(expr)
功能说明:获得指定字段的向上取整数的结果。
返回结果类型:与指定字段的原始数据类型一致。
适用数据类型:数值类型。
适用于: 表和超级表。
嵌套子查询支持:适用于内层查询和外层查询。
使用说明: 只能与普通列,选择(Selection)、投 影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
COS
COS(expr)
功能说明:获得指定字段的余弦结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
FLOOR
FLOOR(expr)
功能说明:获得指定字段的向下取整数的结果。 其他使用说明参见 CEIL 函数描述。
LOG
LOG(expr1[, expr2])
功能说明:获得 expr1 对于底数 expr2 的对数。如果 expr2 参数省略,则返回指定字段的自然对数值。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
POW
POW(expr1, expr2)
功能说明:获得 expr1 的指数为 expr2 的幂。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
ROUND
ROUND(expr[, digits])
功能说明:获得指定字段的四舍五入的结果。
返回结果类型:与指定字段的原始数据类型一致。
适用数据类型:
expr
:数值类型。digits
:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
expr
或digits
为 NULL,返回 NULL。 - 若指定了
digits
,则会保留digits
位小数,默认为 0。 - 若输入值是 INTEGER 类型, 无论
digits
值为多少,都只会返回 INTEGER 类型,不会保留小数。 digits
大于零表示对小数位进行操作,四舍五入到digits
位小数。若小数位数小于digits
位,不进行四舍五入操 作,直接返回。digits
小于零表示丢掉小数位,并将数字四舍五入到小数点左侧digits
位。若小数点左侧的位数小于digits
位,返回 0。- 由于暂未支持 DECIMAL 类型,所以该函数会用 DOUBLE 和 FLOAT 来表示包含小数的结果,但是 DOUBLE 和 FLOAT 是有精度上限的,当位数太多时使用该函数可能没有意义。
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select round(8888.88);
round(8888.88) |
============================
8889.000000000000000 |
taos> select round(8888.88,-1);
round(8888.88,-1) |
============================
8890.000000000000000 |
SIN
SIN(expr)
功能说明:获得指定字段的正弦结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
SQRT
SQRT(expr)
功能说明:获得指定字段的平方根。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
TAN
TAN(expr)
功能说明:获得指定字段的正切结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
PI
PI()
功能说明:返回圆周率 π 的值。
返回结果类型:DOUBLE。
适用数据类型:无。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- π ≈ 3.141592653589793。
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select pi();
pi() |
============================
3.141592653589793 |
TRUNCATE
TRUNCATE(expr, digits)
功能说明:获得指定字段按照指定位数截断的值。
返回结果类型:与 expr
字段的原始数据类型一致。
适用数据类型:
expr
:数值类型。digits
:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
expr
或digits
为 NULL,返回 NULL。 - 截取指按保留位数直接进行截取,没有四舍五入。
digits
大于零表示对小数位进行操作,截取到digits
位小数,若小数位数小于digits
位,不进行截取操作,直接返回。digits
等于零表示丢掉小数位。digits
小于零表示丢掉小数位,并将小数点左侧digits
位置0
。若小数点左侧的位数小于digits
位,返回 0。- 由于暂未支持 DECIMAL 类型,所以该函数会用 DOUBLE 和 FLOAT 来表示包含小数的结果,但是 DOUBLE 和 FLOAT 是有精度上限的,当位数太多时使用该函数可能没有意义。
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select truncate(8888.88, 0);
truncate(8888.88, 0) |
============================
8888.000000000000000 |
taos> select truncate(8888.88, -1);
truncate(8888.88, -1) |
============================
8880.000000000000000 |
EXP
EXP(expr)
功能说明:返回 e(自然对数的底)的指定乘方后的值。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为 NULL,返回 NULL。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select exp(2);
exp(2) |
============================
7.389056098930650 |
LN
LN(expr)
功能说明:返回指定参数的自然对数。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为 NULL,返回 NULL。 - 如果
epxr
小于等于 0,返回 NULL。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select ln(10);
ln(10) |
============================
2.302585092994046 |
MOD
MOD(expr1, expr2)
功能说明:计算 expr1 % expr2 的结果。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr2
为 0 则返回 NULL。 - 如果
expr1
或expr2
为 NULL,返回 NULL。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select mod(10,3);
mod(10,3) |
============================
1.000000000000000 |
taos> select mod(1,0);
mod(1,0) |
============================
NULL |
RAND
RAND([seed])
功能说明:返回一个从0到1均匀分布的随机数。
返回结果类型:DOUBLE。
适用数据类型:
seed
:INTEGER。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果指定了
seed
值,那么将会用指定的seed
作为随机种子,确保生成的随机数序列具有确定性。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select rand();
rand() |
============================
0.202092426923147 |
taos> select rand();
rand() |
============================
0.131537788143166 |
taos> select rand(1);
rand(1) |
============================
0.000007826369259 |
taos> select rand(1);
rand(1) |
============================
0.000007826369259 |
SIGN
SIGN(expr)
功能说明:返回指定参数的符号。
返回结果类型:与指定字段的原始数据类型一致。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为负,返回 -1 , - 如果
expr
为正,返回 1 , - 如果
expr
为 0 ,返回 0 。 - 如果
expr
为 NULL ,返回 NULL 。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select sign(-1);
sign(-1) |
========================
-1 |
taos> select sign(1);
sign(1) |
========================
1 |
taos> select sign(0);
sign(0) |
========================
0 |
DEGREES
DEGREES(expr)
功能说明:计算指定参数由弧度值转为角度后的值。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为 NULL,则返回 NULL。 - degree = radian * 180 / π。
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select degrees(PI());
degrees(pi()) |
============================
180.000000000000000 |
RADIANS
RADIANS(expr)
功能说明:计算指定参数由角度值转为弧度后的值。
返回结果类型:DOUBLE。
适用数据类型:数值类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为 NULL,则返回 NULL。 - radian = degree * π / 180。
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
举例:
taos> select radians(180);
radians(180) |
============================
3.141592653589793 |
字符串函数
字符串函数的输入参数为字符串类型,返回结果为数值类型或字符串类型。
CHAR_LENGTH
CHAR_LENGTH(expr)
功能说明:以字符计数的字符串长度。
返回结果类型:BIGINT。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 与
LENGTH()
函数不同在于,对于多字节字符,比如中文字符,CHAR_LENGTH()
函数会将其算做一个字符,长度为 1,而LENGTH()
会计算其字节数,长度为 3。比如CHAR_LENGTH('你好') = 2
,LENGTH('你好') = 6
。 - 如果
expr
为 NULL,返回 NULL。
举例:
taos> select char_length('Hello world');
char_length('Hello world') |
=============================
11 |
taos> select char_length('你好 世界');
char_length('你好 世界') |
===============================
5 |
CONCAT
CONCAT(expr1, expr2 [, expr] ... )
功能说明:字符串连接函数。
返回结果类型:如果所有参数均为 VARCHAR 类型,则结果类型为 VARCHAR。如果参数包含NCHAR类型,则结果类型为NCHAR。如果参数包含NULL值,则输出值为NULL。
适用数据类型:VARCHAR, NCHAR。 该函数最小参数个数为2个,最大参数个数为8个。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
CONCAT_WS
CONCAT_WS(separator_expr, expr1, expr2 [, expr] ...)
功能说明:带分隔符的字符串连接函数。
返回结果类型:如果所有参数均为VARCHAR类型,则结果类型为VARCHAR。如果参数包含NCHAR类型,则结果类型为NCHAR。如果参数包含NULL值,则输出值为NULL。
适用数据类型:VARCHAR, NCHAR。 该函数最小参数个数为3个,最大参数个数为9个。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
LENGTH
LENGTH(expr)
功能说明:以字节计数的长度。
返回结果类型:BIGINT。
适用数据类型:VARCHAR, NCHAR, VARBINARY。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
LOWER
LOWER(expr)
功能说明:将字符串参数值转换为全小写字母。
返回结果类型:与输入字段的原始类型相同。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
LTRIM
LTRIM(expr)
功能说明:返回清除左边空格后的字符串。
返回结果类型:与输入字段的原始类型相同。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
RTRIM
RTRIM(expr)
功能说明:返回清除右边空格后的字符串。
返回结果类型:与输入字段的原始类型相同。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
TRIM
TRIM([{LEADING | TRAILING | BOTH} [remstr] FROM] expr)
TRIM([remstr FROM] expr)
功能说明:返回去掉了所有 remstr 前缀或后缀的字符串 epxr 。
返回结果类型:与输入字段 epxr 的原始类型相同。
适用数据类型:
- remstr:VARCHAR,NCHAR。
- epxr:VARCHAR,NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 第一个可选变量[LEADING | BOTH | TRAILING]指定要剪裁字符串的哪一侧:
- LEADING 将移除字符串开头的指定字符。
- TRAILING 将移除字符串末尾的指定字符。
- BOTH(默认值)将移除字符串开头和末尾的指定字符。
- 第二个可选变量[remstr]指定要裁剪掉的字符串:
- 如果不指定 remstr ,默认裁剪空格。
- remstr 可以指定多个字符,如trim('ab' from 'abacd') ,此时会将 'ab' 看做一个整体来裁剪,得到裁剪结果 'acd'。
- 若 expr 为 NULL, 返回 NULL。
- 该函数是多字节安全的。
举例:
taos> select trim(' a ');
trim(' a ') |
=============================
a |
taos> select trim(leading from ' a ');
trim(leading from ' a ') |
==========================================
a |
taos> select trim(leading 'b' from 'bbbbbbbba ');
trim(leading 'b' from 'bbbbbbbba ') |
==============================================
a |
taos> select trim(both 'b' from 'bbbbbabbbbbb');
trim(both 'b' from 'bbbbbabbbbbb') |
=====================================
a |
SUBSTRING/SUBSTR
SUBSTRING/SUBSTR(expr, pos [, len])
SUBSTRING/SUBSTR(expr FROM pos [FOR len])
功能说明:返回字符串 expr
在 pos
位置开始的子串,若指定了 len
,则返回在 pos
位置开始,长度为 len
的子串。
返回结果类型:与输入字段 expr
的原始类型相同。
适用数据类型:
expr
:VARCHAR,NCHAR。pos
:整数类型。len
:整数类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
pos
为正数,则返回的结果为expr
从左到右开始数pos
位置开始的右侧的子串。 - 若
pos
为负数,则返回的结果为expr
从右到左开始数pos
位置 开始的右侧的子串。 - 任意参数为 NULL,返回 NULL。
- 该函数是多字节安全的。
- 若
len
小于 1,返回空串。 pos
是 1-base 的,若pos
为 0,返回空串。- 若
pos
+len
大于len(expr)
,返回从pos
开始到字符串结尾的子串,等同于执行substring(expr, pos)
。
举例:
taos> select substring('tdengine', 0);
substring('tdengine', 0) |
===========================
|
taos> select substring('tdengine', 3);
substring('tdengine', 3) |
===========================
engine |
taos> select substring('tdengine', 3,3);
substring('tdengine', 3,3) |
=============================
eng |
taos> select substring('tdengine', -3,3);
substring('tdengine', -3,3) |
==============================
ine |
taos> select substring('tdengine', -3,-3);
substring('tdengine', -3,-3) |
===============================
|
SUBSTRING_INDEX
SUBSTRING_INDEX(expr, delim, count)
功能说明:返回字符串 expr
在出现指定次数分隔符的位置截取的子串。
返回结果类型:与输入字段 expr
的原始类型相同。
适用数据类型:
expr
:VARCHAR,NCHAR。delim
:VARCHAR, NCHAR。count
:INTEGER。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
count
为正数,则返回的结果为expr
从左到右开始数第count
次 出现delim
的位置左侧的字符串。 - 若
count
为负数,则返回的结果为expr
从右到左开始数第count
的绝对值次 出现delim
的位置右侧的字符串。 - 任意参数为 NULL,返回 NULL。
- 该函数是多字节安全的。
举例:
taos> select substring_index('www.taosdata.com','.',2);
substring_index('www.taosdata.com','.',2) |
============================================
www.taosdata |
taos> select substring_index('www.taosdata.com','.',-2);
substring_index('www.taosdata.com','.',-2) |
=============================================
taosdata.com |
UPPER
UPPER(expr)
功能说明:将字符串参数值转换为全大写字母。
返回结果类型:与输入字段的原始类型相同。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
CHAR
CHAR(expr1 [, expr2] [, epxr3] ...)
功能说明:将输入参数当作整数,并返回这些整数在 ASCII 编码中对应的字符。
返回结果类型:VARCHAR。
适用数据类型:整数类型,VARCHAR,NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 输入的值超过 255 会被转化成多字节的结果,如
CHAR(256)
等同于CHAR(1,0)
,CHAR(256 * 256)
等同于CHAR(1,0,0)
。 - 输入参数的 NULL 值会被跳过。
- 输入参数若为字符串类型,会将其转换为数值类型处理。
- 若输入的参数对应的字符为不可打印字符,返回值中仍有该参数对应的字符,但是可能无法显示出来。
举例:
taos> select char(77);
char(77) |
===========
M |
taos> select char(77,77);
char(77,77) |
==============
MM |
taos> select char(77 * 256 + 77);
char(77 * 256 + 77) |
======================
MM |
taos> select char(77,NULL,77);
char(77,null,77) |
===================
MM |
ASCII
ASCII(expr)
功能说明:返回字符串第一个字符的 ASCII 码。
返回结果数据类型:BIGINT。
适用数据类型:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 如果
expr
为 NULL,返回 NULL。 - 如果
expr
的第一个字符为多字节字符,只会返回该字符第一个字节的值对应的 ASCII 码。
举例:
taos> select ascii('testascii');
ascii('testascii') |
=====================
116 |
POSITION
POSITION(expr1 IN expr2)
功能说明:计算字符串 expr1
在字符串 expr2
中的位置。
返回结果类型:BIGINT。
适用数据类型:
expr1
:VARCHAR, NCHAR。expr2
:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
expr1
或expr2
为 NULL,返回 NULL。 - 若
expr1
在expr2
中不存在,返回 0。 - 若
expr1
为空串,认为expr1
在expr2
中总能匹配成功,返回 1。 - 返回的位置是 1-base 的。
- 该函数是多字节安全的。
举例:
taos> select position('a' in 'cba');
position('a' in 'cba') |
=========================
3 |
taos> select position('' in 'cba');
position('' in 'cba') |
========================
1 |
taos> select position('d' in 'cba');
position('d' in 'cba') |
=========================
0 |
REPLACE
REPLACE(expr, from_str, to_str)
功能说明:将字符串中的 from_str
全部替换为 to_str
。
返回结果类型:与输入字段 expr
的原始类型相同。
适用数据类型:
expr
:VARCHAR, NCHAR。from_str
:VARCHAR, NCHAR。to_str
:VARCHAR, NCHAR。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 该函数是大小写敏感的。
- 任意参数为 NULL,返回 NULL。
- 该函数是多字节安全的。
举例:
taos> select replace('aabbccAABBCC', 'AA', 'DD');
replace('aabbccAABBCC', 'AA', 'DD') |
======================================
aabbccDDBBCC |
REPEAT
REPEAT(expr, count)
功能说明:返回将字符串重复指定次数得到的字符串。
返回结果类型:与输入字段 expr
的原始类型相同。
适用数据类型:
expr
: VARCHAR,NCHAR。count
:INTEGER。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
count < 1
,返回空串。 - 若
expr
或count
为 NULL,返回 NULL。
举例:
taos> select repeat('abc',5);
repeat('abc',5) |
============================
abcabcabcabcabc |
taos> select repeat('abc',-1);
repeat('abc',-1) |
===================
|
转换函数
转换函数将值从一种数据类型转换为另一种数据类型。
CAST
CAST(expr AS type_name)
功能说明:数据类型转换函数,返回 expr 转换为 type_name 指定的类型后的结果。
返回结果类型:CAST 中指定的类型(type_name) 。
适用数据类型:输入参数 expr 的类型可以是除JSON和VARBINARY外的所有类型。如果 type_name 为 VARBINARY,则 expr 只能是 VARCHAR 类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 对于不能支持的类型转换会直接报错。
- 对于类型支持但某些值无法正确转换的情况,对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况: 1)字符串类型转换数值类型时可能出现的无效字符情况,例如"a"可能转为0,但不会报错。 2)转换到数值类型时,数值大于type_name可表示的范围时,则会溢出,但不会报错。 3)转换到字符串类型时,如果转换后长度超过type_name中指定的长度,则会截断,但不会报错。
TO_ISO8601
TO_ISO8601(expr [, timezone])
功能说明:将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式,并附加时区信息。timezone 参数允许用户为输出结果指定附带任意时区信息。如果 timezone 参数省略,输出结果则附带当前客户端的系统时区信息。
返回结果数据类型:VARCHAR 类型。
适用数据类型:INTEGER, TIMESTAMP。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- timezone 参数允许输入的时区格式为: [z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如,TO_ISO8601(1, "+00:00")。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
TO_JSON
TO_JSON(str_literal)
功能说明: 将字符串常量转换为 JSON 类型。
返回结果数据类型: JSON。
适用数据类型: JSON 字符串,形如 '{ "literal" : literal }'。'{}'表示空值。键必须为字符串字面量,值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal中不支持转义符。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
TO_UNIXTIMESTAMP
TO_UNIXTIMESTAMP(expr [, return_timestamp])
return_timestamp: {
0
| 1
}
功能说明:将日期时间格式的字符串转换成为 UNIX 时间戳。
返回结果数据类型:BIGINT, TIMESTAMP。
应用字段:VARCHAR, NCHAR。
嵌套子查 询支持:适用于内层查询和外层查询。
适用于:表和超级表。
使用说明:
- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准,无法转换的字符串格式将返回 NULL。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
- return_timestamp 指定函数返回值是否为时间戳类型,设置为1时返回 TIMESTAMP 类型,设置为0时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。
TO_CHAR
TO_CHAR(ts, format_str_literal)
功能说明: 将timestamp类型按照指定格式转换为字符串
版本: ver-3.2.2.0
返回结果数据类型: VARCHAR
应用字段: TIMESTAMP
嵌套子查询支持: 适用于内层查询和外层查询
适用于: 表和超级表
支持的格式
格式 | 说明 | 例子 |
---|---|---|
AM,am,PM,pm | 无点分隔的上午下午 | 07:00:00am |
A.M.,a.m.,P.M.,p.m. | 有点分隔的上午下午 | 07:00:00a.m. |
YYYY,yyyy | 年, 4个及以上数字 | 2023-10-10 |
YYY,yyy | 年, 最后3位数字 | 023-10-10 |
YY,yy | 年, 最后2位数字 | 23-10-10 |
Y,y | 年, 最后一位数字 | 3-10-10 |
MONTH | 月, 全大写 | 2023-JANUARY-01 |
Month | 月, 首字母大写 | 2023-January-01 |
month | 月, 全小写 | 2023-january-01 |
MON | 月, 缩写, 全大写(三个字符) | JAN, SEP |
Mon | 月, 缩写, 首字母大写 | Jan, Sep |
mon | 月, 缩写, 全小写 | jan, sep |
MM,mm | 月, 数字 01-12 | 2023-01-01 |
DD,dd | 月日, 01-31 | |
DAY | 周日, 全大写 | MONDAY |
Day | 周日, 首字符大写 | Monday |
day | 周日, 全小写 | monday |
DY | 周日, 缩写, 全大写 | MON |
Dy | 周日, 缩写, 首字符大写 | Mon |
dy | 周日, 缩写, 全小写 | mon |
DDD | 年日, 001-366 | |
D,d | 周日, 数字, 1-7, Sunday(1) to Saturday(7) | |
HH24,hh24 | 小时, 00-23 | 2023-01-30 23:59:59 |
hh12,HH12, hh, HH | 小时, 01-12 | 2023-01-30 12:59:59PM |
MI,mi | 分钟, 00-59 | |
SS,ss | 秒, 00-59 | |
MS,ms | 毫秒, 000-999 | |
US,us | 微秒, 000000-999999 | |
NS,ns | 纳秒, 000000000-999999999 | |
TZH,tzh | 时区小时 | 2023-01-30 11:59:59PM +08 |
使用说明:
Month
,Day
等的输出格式是左对齐的, 右侧添加空格, 如2023-OCTOBER -01
,2023-SEPTEMBER-01
, 9月是月份中英文字母数最长的, 因此9月没有空格. 星期类似.- 使用
ms
,us
,ns
时, 以上三种格式的输出只在精度上不同, 比如ts为1697182085123
,ms
的输出为123
,us
的输出为123000
,ns
的输出为123000000
. - 时间格式中无法匹配规则的内容会直接输出. 如果想要在格式串中指定某些能够匹配规则的部分不做转换, 可以使用双引号, 如
to_char(ts, 'yyyy-mm-dd "is formated by yyyy-mm-dd"')
. 如果想要输出双引号, 那么在双引号之前加一个反斜杠, 如to_char(ts, '\"yyyy-mm-dd\"')
将会输出"2023-10-10"
. - 那些输出是数字的格式, 如
YYYY
,DD
, 大写与小写意义相同, 即yyyy
和YYYY
可以互换. - 推荐在时间格式中带时区信息,如果不带则默认输出的时区为服务端或客户端所配置的时区.
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
TO_TIMESTAMP
TO_TIMESTAMP(ts_str_literal, format_str_literal)
功能说明: 将字符串按照指定格式转化为时间戳.
版本: ver-3.2.2.0
返回结果数据类型: TIMESTAMP
应用字段: VARCHAR
嵌套子查询支持: 适用于内层查询和外层查询
适用于: 表和超级表
支持的格式: 与to_char
相同
使用说明:
- 若
ms
,us
,ns
同时指定, 那么结果时间戳包含上述三个字段的和. 如to_timestamp('2023-10-10 10:10:10.123.000456.000000789', 'yyyy-mm-dd hh:mi:ss.ms.us.ns')
输出为2023-10-10 10:10:10.123456789
对应的时间戳. MONTH
,MON
,DAY
,DY
以及其他输出为数字的格式的大小写意义相同, 如to_timestamp('2023-JANUARY-01', 'YYYY-month-dd')
,month
可以被替换为MONTH
或者Month
.- 如果同一字段被指定了多次, 那么前面的指定将会被覆盖. 如
to_timestamp('2023-22-10-10', 'yyyy-yy-MM-dd')
, 输出年份是2022
. - 为避免转换时使用了非预期的时区,推荐在时间中携带时区信息,例如'2023-10-10 10:10:10+08',如果未指定时区则默认时区为服务端或客户端指定的时区。
- 如果没有指定完整的时间,那么默认时间值为指定或默认时区的
1970-01-01 00:00:00
, 未指定部分使用该默认值中的对应部分. 暂不支持只指定年日而不指定月日的格式, 如'yyyy-mm-DDD', 支持'yyyy-mm-DD'. - 如果格式串中有
AM
,PM
等, 那么小时必须是12小时制, 范围必须是01-12. to_timestamp
转换具有一定的容错机制, 在格式串和时间戳串不完全对应时, 有时也可转换, 如:to_timestamp('200101/2', 'yyyyMM1/dd')
, 格式串中多出来的1会被丢弃. 格式串与时间戳串中多余的空格字符(空格, tab等)也会被 自动忽略. 如to_timestamp(' 23 年 - 1 月 - 01 日 ', 'yy 年-MM月-dd日')
可以被成功转换. 虽然MM
等字段需要两个数字对应(只有一位时前面补0), 在to_timestamp
时, 一个数字也可以成功转换.- 输出时间戳的精度与查询表的精度相同, 若查询未指定表, 则输出精度为毫秒. 如
select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns')
的输出将会把微秒和纳秒进行截断. 如果指定一张纳秒表, 那么就不会发生截断, 如select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns') from db_ns.table_ns limit 1
.
时间和日期函数
时间和日期函数对时间戳类型进行操作。
所有返回当前时间的函数,如NOW、TODAY和TIMEZONE,在一条SQL语句中不论出现多少次都只会被计算一次。
NOW
NOW()
功能说明:返回客户端当前系统时间。
返回结果数据类型:TIMESTAMP。
应用字段:在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。
适用于:表和超级表。
嵌套子查询支持:适用于内层查询和外层查询。
使用说明:
- 支持时间加减操作,如 NOW() + 1s, 支持的时间单位如下: b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
TIMEDIFF
TIMEDIFF(expr1, expr2 [, time_unit])
功能说明:返回时间戳 expr1
- expr2
的结果,结果可能为负,并近似到时间单位 time_unit
指定的精度。
返回结果类型:BIGINT。
适用数据类型:
expr1
:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。expr2
:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。time_unit
:见使用说明。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 支持的时间单位
time_unit
如下: 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。 - 如果时间单位
time_unit
未指定, 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 - 输入包含不符合时间日期格式的字符串则返回 NULL。
expr1
或expr2
为 NULL,返回 NULL。time_unit
为 NULL,等同于未指定时间单位。- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
举例:
taos> select timediff('2022-01-01 08:00:00', '2022-01-01 08:00:01',1s);
timediff('2022-01-01 08:00:00', '2022-01-01 08:00:01',1s) |
============================================================
-1 |
taos> select timediff('2022-01-01 08:00:01', '2022-01-01 08:00:00',1s);
timediff('2022-01-01 08:00:01', '2022-01-01 08:00:00',1s) |
============================================================
1 |
TIMETRUNCATE
TIMETRUNCATE(expr, time_unit [, use_current_timezone])
use_current_timezone: {
0
| 1
}
功能说明:将时间戳按照指定时间单位 time_unit 进行截断。
返回结果数据类型:TIMESTAMP。
应用字段:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。
适用于:表和超级表。
使用说明:
- 支持的时间单位 time_unit 如下: 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
- 输入包含不符合时间日期格式的字符串则返回 NULL。
- 当使用 1d/1w 作为时间单位对时间戳进行截断时, 可通过设置 use_current_timezone 参数指定是否根据当前时区进行截断处理。 值 0 表示使用 UTC 时区进行截断,值 1 表示使用当前时区进行截断。 例如客户端所配置时区为 UTC+0800, 则 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) 返回结果为东八区时间 '2020-01-01 08:00:00'。 而使用 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) 时,返回结果为东八区时间 '2020-01-01 00:00:00'。 当不指定 use_current_timezone 时,use_current_timezone 默认值为 1 。
- 当将时间值截断到一周(1w)时,timetruncate 的计算是基于 Unix 时间戳(1970年1月1日00:00:00 UTC)进行的。Unix 时间戳始于星期四, 因此所有截断后的日期都是星期四。
TIMEZONE
TIMEZONE()
功能说明:返回客户端当前时区信息。
返回结果数据类型:VARCHAR。
应用字段:无
适用于:表和超级表。
TODAY
TODAY()
功能说明:返回客户端当日零时的系统时间。
返回结果数据类型:TIMESTAMP。
应用字段:在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。
适用于:表和超级表。
使用说明:
- 支持时间加减操作,如 TODAY() + 1s, 支持的时间单位如下: b(纳秒),u(微秒),a(毫秒),s(秒),m(分),h(小时),d(天),w(周)。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
WEEK
WEEK(expr [, mode])
功能说明:返回输入日期的周数。
返回结果类型:BIGINT。
适用数据类型:
expr
:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。mode
:0 - 7 之间的整数。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 若
expr
为 NULL,返回 NULL。 - 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
mode
用来指定一周是从周日开始还是周一开始,以及指定返回值范围是 1 - 53 还是 0 - 53。下表详细描述不同的 mode 对应的计算方法:
Mode | 每周的第一天 | 返回值范围 | 第 1 周的计算方法 |
---|---|---|---|
0 | 周日 | 0 - 53 | 第一个包含周日的周为第 1 周 |
1 | 周一 | 0 - 53 | 第一个包含四天及以上的周为第 1 周 |
2 | 周日 | 1 - 53 | 第一个包含周日的周为第 1 周 |
3 | 周一 | 1 - 53 | 第一个包含四天及以上的周为第 1 周 |
4 | 周日 | 0 - 53 | 第一个包含四天及以上的周为第 1 周 |
5 | 周一 | 0 - 53 | 第一个包含周一的周为第 1 周 |
6 | 周日 | 1 - 53 | 第一个包含四天及以上的周为第 1 周 |
7 | 周一 | 1 - 53 | 第一个包含周一的周为第 1 周 |
- 当返回值范围为0 - 53时,第 1 周之前的日期为第 0 周。
- 当返回值范围为1 - 53时,第 1 周之前的日期为上一年的最后一周。
- 以
2000-01-01
为例,- 在
mode=0
时返回值为0
,因为该年第一个周日为2000-01-02
,从2000-01-02
起才是第 1 周,所以2000-01-01
为第 0 周,返回 0。 - 在
mode=1
时返回值为0
,因为2000-01-01
所在的周只有两天,分别是2000-01-01(周六)
和2000-01-02(周日)
,所以2000-01-03
起才是第一周,2000-01-01
为第 0 周,返回 0。 - 在
mode=2
时返回值为52
,因为从2000-01-02
起才是第 1 周,并且返回值范围为 1-53,所以2000-01-01
算做上一年的最后一周,即 1999 年的第 52 周,返回 52。
- 在
举例:
taos> select week('2000-01-01',0);
week('2000-01-01',0) |
========================
0 |
taos> select week('2000-01-01',1);
week('2000-01-01',1) |
========================
0 |
taos> select week('2000-01-01',2);
week('2000-01-01',2) |
========================
52 |
taos> select week('2000-01-01',3);
week('2000-01-01',3) |
========================
52 |
WEEKOFYEAR
WEEKOFYEAR(expr)
功能说明:返回输入日期的周数。
返回结果类型:BIGINT。
适用数据类型:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 等同于
WEEK(expr, 3)
,即在每周第一天是周一,返回值范围为 1 - 53,第一个包含四天及以上的周为第 1 周的条件下判断输入日期的周数。 - 若
expr
为 NULL,返回 NULL。 - 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
举例:
taos> select weekofyear('2000-01-01');
weekofyear('2000-01-01') |
===========================
52 |
WEEKDAY
WEEKDAY(expr)
功能说明:返回输入日期是周几。
返回结果类型:BIGINT。
适用数据类型:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 返回值 0 代表周日,1 代表周一 ... 6 代表周六。
- 若
expr
为 NULL,返回 NULL。 - 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
举例:
taos> select weekday('2000-01-01');
weekday('2000-01-01') |
========================
5 |
DAYOFWEEK
DAYOFWEEK(expr)
功能说明:返回输入日期是周几。
返回结果类型:BIGINT。
适用数据类型:表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型,或符合日期时间格式的 VARCHAR, NCHAR 类型。
嵌套子查询支持:适用于内层查询和外层查询。
适用于: 表和超级表。
使用说明:
- 返回值 1 代表周日,2 代表周一 ... 7 代表周六
- 若
expr
为 NULL,返回 NULL。 - 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
举例:
taos> select dayofweek('2000-01-01');
dayofweek('2000-01-01') |
==========================
7 |
聚合函数
聚合函数为查询结果集的每一个分组返回单个结果行。可以由 GROUP BY 或窗口切分子句指定分组,如果没有,则整个查询结果集视为一个分组。
TDengine 支持针对数据的聚合查询。提供如下聚合函数。
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"算法的近似结果对于输入数据顺序敏感,对超级表查询时不同的输入排序结果可能会有微小的误差。
AVG
AVG(expr)
功能说明:统计指定字段的平均值。
返回数据类型:DOUBLE。
适用数据类型:数值类型。
适用于:表和超级表。
COUNT
COUNT({* | expr})
功能说明:统计指定字段的记录行数。
返回数据类型:BIGINT。
适用数据类型:全部类型字段。
适用于:表和超级表。
使用说明:
- 可以使用星号(*)来替代具体的字段,使用星号(*)返回全部记录数量。
- 如果统计字段是具体的列,则返回该列中非 NULL 值的记录数量。
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等函数混合使用。
LEASTSQUARES
LEASTSQUARES(expr, start_val, step_val)
功能说明:统计表中某列的值的拟合直线方程。start_val 是自变量初始值,step_val 是自变量的步长值。
返回数据类型:字符串表达式(斜率, 截距)。
适用数据类型:expr 必须是数值类型。
适用于:表。
SPREAD
SPREAD(expr)
功能说明:统计表中某列的最大值和最小值之差。
返回数据类型:DOUBLE。
适用数据类型:INTEGER, TIMESTAMP。
适用于:表和超级表。
STDDEV/STDDEV_POP
STDDEV/STDDEV_POP(expr)
功能说明:统计表中某列的总体标准差。
返回数据类型:DOUBLE。
适用数据类型:数值类型。
适用于:表 和超级表。
举例:
taos> select id from test_stddev;
id |
==============
1 |
2 |
3 |
4 |
5 |
taos> select stddev_pop(id) from test_stddev;
stddev_pop(id) |
============================
1.414213562373095 |
VAR_POP
VAR_POP(expr)
功能说明:统计表中某列的总体方差。
返回数据类型:DOUBLE。
适用数据类型:数值类型。
适用于:表和超级表。
举例:
taos> select id from test_var;
id |
==============
3 |
1 |
2 |
4 |
5 |
taos> select var_pop(id) from test_var;
var_pop(id) |
============================
2.000000000000000 |
SUM
SUM(expr)
功能说明:统计表/超级表中某列的和。
返回数据类型:DOUBLE, BIGINT。
适用数据类型:数值类型。
适用于:表和超级表。
HYPERLOGLOG
HYPERLOGLOG(expr)
功能说明:
- 采用 hyperloglog 算法,返回某列的基数。该算法在数据量很大的情况下,可以明显降低内存的占用,求出来的基数是个估算值,标准误差(标准误差是多次实验,每次的平均数的标准差,不是与真实结果的误差)为 0.81%。
- 在数据量较少的时候该算法不是很准确,可以使用 select count(data) from (select unique(col) as data from table) 的方法。
返回结果类型:INTEGER。
适用数据类型:任何类型。
适用于:表和超级表。
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。
选择函数
选择函数根据语义在查询结果集中选择一行或多行结果返回。用户可以同时指定输出 ts 列或其他列 (包括 tbname 和标签列),这样就可以方便地知道被选出的值是源于哪个数据行的。
BOTTOM
BOTTOM(expr, k)
功能说明:统计表/超级表中某列的值最小 k 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。
返回数据类型:同应用的字段。
适用数据类型:数值类型。
适用于:表和超级表。
使用说明:
- k值取值范围 1≤k≤100;
- 系统同时返回该记录关联的时间戳列;
- 限制:BOTTOM 函数不支持 FILL 子句。
FIRST
FIRST(expr)
功能说明:统计表/超级表中某列的值最先写入的非 NULL 值。
返回数据类型:同应用的字段。
适用数据类型:所有字段。
适用于:表和超级表。
使用说明:
- 如果要返回各个列的首个(时间戳最小)非 NULL 值,可以使用 FIRST(*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,FIRST(*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。
- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL;
- 如果结果集中所有列全部为 NULL 值,则不返回结果。
- 对于存在复合主键的表的查询,若最小时间戳的数据有多条,则只有对应的复合主键最小的数据被返回。
INTERP
INTERP(expr [, ignore_null_values])
ignore_null_values: {
0
| 1
}
功能说明:返回指定时间截面指定列的记录值或插值。ignore_null_values 参数的值可以是 0 或 1,为 1 时表示忽略 NULL 值, 缺省值为0。
返回数据类型:同字段类型。
适用数据类型:数值类型。
适用于:表和超级表。
使用说明
- INTERP 用于在指定时间断面获取指定列的记录值,如果该时间断面不存在符合条件的行数据,那么会根据 FILL 参数的设定进行插值。
- INTERP 的输入数据为指定列的数据,可以通过条件语句(where 子句)来对原始列数据进行过滤,如果没有指定过滤条件则输入为全部数据。
- INTERP 需要同时与 RANGE,EVERY 和 FILL 关键字一起使用。
- INTERP 的输出时间范围根据 RANGE(timestamp1, timestamp2)字段来指定,需满足 timestamp1 <= timestamp2。其中 timestamp1 为输出时间范围的起始值,即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录,timestamp2 为输出时间范围的结束值 ,即输出的最后一条记录的 timestamp 不能大于 timestamp2。
- INTERP 根据 EVERY(time_unit) 字段来确定输出时间范围内的结果条数,即从 timestamp1 开始每隔固定长度的时间(time_unit 值)进行插值,time_unit 可取值时间单位:1a(毫秒),1s(秒),1m(分),1h(小时),1d(天),1w(周)。例如 EVERY(500a) 将对于指定数据每500毫秒间隔进行一次插值.
- INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值。关于 FILL 子句如何使用请参考 FILL 子句
- INTERP 可以在 RANGE 字段中只指定唯一的时间戳对单个时间点进行插值,在这种情况下,EVERY 字段可以省略。例如:SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00') FILL(linear).
- INTERP 作用于超级表时, 会将该超级表下的所有子表数据按照主键列排序后进行插值计算,也可以搭配 PARTITION BY tbname 使用,将结果强制规约到单个时间线。
- INTERP 可以与伪列 _irowts 一起使用,返回插值点所对应的时间戳(3.0.2.0版本以后支持)。
- INTERP 可以与伪列 _isfilled 一起使用,显示返回结果是否为原始记录或插值算法产生的数据(3.0.3.0版本以后支持)。
- INTERP 对于带复合主键的表的查询,若存在相同时间戳的数据,则只有对应的复合主键最小的数据参与运算。
LAST
LAST(expr)
功能说明:统计表/超级表中某列的值最后写入的非 NULL 值。
返回数据类型:同应用的字段。
适用数据类型:所有字段。
适用于:表和超级表。
使用说明:
- 如果要返回各个列的最后(时间戳最大)一个非 NULL 值,可以使用 LAST(*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,LAST(*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。
- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL;如果结果集中所有列全部为 NULL 值,则不返回结果。
- 在用于超级表时,时间戳完全一样且同为最大的数据行可能有多个,那么会从中随机返回一条,而并不保证多次运行所挑选的数据行必然一致。
- 对于存在复合主键的表的查询,若最大时间戳的数据有多条,则只有对应的复合主键最大的数据被返回。
LAST_ROW
LAST_ROW(expr)
功能说明:返回表/超级表的最后一条记录。
返回数据类型:同应用的字段。
适用数据类型:所有字段。
适用于:表和超级表。
使用说明:
- 如果要返回各个列的最后一条记录(时间戳最大),可以使用 LAST_ROW(*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,LAST_ROW(*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。
- 在用于超级表时,时间戳完全一样且同为最大的数据行可能有 多个,那么会从中随机返回一条,而并不保证多次运行所挑选的数据行必然一致。
- 不能与 INTERVAL 一起使用。
- 与 LAST 函数一样,对于存在复合主键的表的查询,若最大时间戳的数据有多条,则只有对应的复合主键最大的数据被返回。
MAX
MAX(expr)
功能说明:统计表/超级表中某列的值最大值。
返回数据类型:同应用的字段。
适用数据类型:数值类型, VARCHAR,NCHAR。
适用于:表和超级表。
使用说明:max 函数可 以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值。
MIN
MIN(expr)
功能说明:统计表/超级表中某列的值最小值。
返回数据类型:同应用的字段。
适用数据类型:数值类型, VARCHAR,NCHAR。
适用于:表和超级表。
使用说明:min 函数可以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值。
MODE
MODE(expr)
功能说明:返回出现频率最高的值,若存在多个频率相同的最高值,则随机输出其中某个值。
返回数据类型:与输入数据类型一致。
适用数据类型:全部类型字段。
适用于:表和超级表。
SAMPLE
SAMPLE(expr, k)
功能说明: 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。
返回结果类型: 同原始数据类型。
适用数据类型: 全部类型字段。
嵌套子查询支持: 适用于内层查询和外层查询。
适用于:表和超级表。
TAIL
TAIL(expr, k [, offset_rows])
功能说明:返回跳过最后 offset_val 个,然后取连续 k 个记录,不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下,该函数功能等效于 order by ts desc LIMIT k OFFSET offset_val
。
参数范围:k: [1,100] offset_val: [0,100]。
返回数据类型:同应用的字段。
适用数据类型:适合于除时间主键列外的任何类型。
适用于:表、超级表。
TOP
TOP(expr, k)
功能说明: 统计表/超级表中某列的值最大 k 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。
返回数据类型:同应用的字段。
适用数据类型:数值类型。
适用于:表和超级表。
使用说明:
- k值取值范围 1≤k≤100;
- 系统同时返回该记录关联的时间戳列;
- 限制:TOP 函数不支持 FILL 子句。
UNIQUE
UNIQUE(expr)
功能说明:返回该列数据首次出现的值。该函数功能与 distinct 相似。对于存在复合主键的表的查询,若最小时间戳的数据有多条,则只有对应的复合主键最小的数据被返回。
返回数据类型:同应用的字段。
适用数据类型:全部类型字段。
适用于: 表和超级表。
时序数据特有函数
时序数据特有函数是 TDengine 为了满足时序数据的查询场景而量身定做出来的。在通用数据库中,实现类似功能通常需要复杂的查询语法,且效率很低。TDengine 以函数 的方式内置了这些功能,最大程度的减轻了用户的使用成本。
CSUM
CSUM(expr)
功能说明:累加和(Cumulative sum),忽略 NULL 值。
返回结果类型: 输入列如果是整数类型返回值为长整型 (int64_t),浮点数返回值为双精度浮点数(Double)。无符号整数类型返回值为无符号长整型(uint64_t)。
适用数据类型:数值类型。
嵌套子查询支持: 适用于内层查询和外层查询。
适用于:表和超级表。
使用说明:
- 不支持 +、-、*、/ 运算,如 csum(col1) + csum(col2)。
- 只能与聚合(Aggregation)函数一起使用。 该函数可以应用在普通表和超级表上。
DERIVATIVE
DERIVATIVE(expr, time_interval, ignore_negative)
ignore_negative: {
0
| 1
}
功能说明:统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定,最小可以是 1 秒(1s);ignore_negative 参数的值可以是 0 或 1,为 1 时表示忽略负值。对于存在复合主键的表的查询,若时间戳相同的数据存在多条,则只有对应的复合主键最小的数据参与运算。
返回数据类型:DOUBLE。
适用数据类型:数值类型。
适用于:表和超级表。
使用说明:
- 可以与选择相关联的列一起使用。 例如: select _rowts, DERIVATIVE() from。
DIFF
DIFF(expr [, ignore_option])
ignore_option: {
0
| 1
| 2
| 3
}
功能说明:统计表中特定列与之前行的当前列有效值之差。 ignore_option 取值为 0|1|2|3 , 可以不填,默认值为 0.
0
表示不忽略(diff结果)负值不忽略 null 值1
表示(diff结果)负值作为 null 值2
表示不忽略(diff结果)负值但忽略 null 值3
表示忽略(diff结果)负值且忽略 null 值- 对于存在复合主键的表的查询,若时间戳相同的数据存在多条,则只有对应的复合主键最小的数据参与运算。
返回数据类型:bool、时间戳及整型数值类型均返回 int_64,浮点类型返回 double, 若 diff 结果溢出则返回溢出后的值。
适用数据类型:数值类型、时间戳和 bool 类型。
适用于:表和超级表。
使用说明:
- diff 是计算本行特定列与同列的前一个有效数据的差值,同列的前一个有效数据:指的是同一列中时间戳较小的最临近的非空值。
- 数值类型 diff 结果为对应的算术差值;时间戳类型根据数据库的时间戳精度进行差值计算;bool 类型计算差值时 true 视为 1, false 视为 0
- 如当前行数据为 null 或者没有找到同列前一个有效数据时,diff 结果为 null
- 忽略负值时( ignore_option 设置为 1 或 3 ),如果 diff 结果为负值,则结果设置为 null,然后根据 null 值过滤规则进行过滤
- 当 diff 结果发生溢出时,结果是否是
应该忽略的负值
取决于逻辑运算结果是正数还是负数,例如 9223372036854775800 - (-9223372036854775806) 的值超出 BIGINT 的范围 ,diff 结果会显示溢出值 -10,但并不 会被作为负值忽略 - 单个语句中可以使用单个或者多个 diff,并且每个 diff 可以指定相同或不同的 ignore_option ,当单个语句中存在多个 diff 时当且仅当某行所有 diff 的结果都为 null ,并且 ignore_option 都设置为忽略 null 值,该行才从结果集中剔除
- 可以选择与相关联的列一起使用。 例如: select _rowts, DIFF() from。
- 当没有复合主键时,如果不同的子表有相同时间戳的数据,会提示 "Duplicate timestamps not allowed"
- 当使用复合主键时,不同子表的时间戳和主键组合可能相同,使用哪一行取决于先找到哪一行,这意味着在这种情况下多次运行 diff() 的结果可能会不同。
IRATE
IRATE(expr)
功能说明:计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率;如果这两个值呈递减关系,那么只取最后一个数用于计算,而不是使用二者差值。对于存在复合主键的表的查询,若时间戳相同的数据存在多条,则只有对应的复合主键最小的数据参与运算。
返回数据类型:DOUBLE。
适用数据类型:数值类型。
适用于:表和超级表。
MAVG
MAVG(expr, k)
功能说明: 计算连续 k 个值的移动平均数(moving average)。如果输入行数小于 k,则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。
返回结果类型: DOUBLE。
适用数据类型: 数值类型。
嵌套子查询支持: 适用于内层查询和外层查询。
适用于:表和超级表。
使用说明:
- 不支持 +、-、*、/ 运算,如 mavg(col1, k1) + mavg(col2, k1);
- 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用;
STATECOUNT
STATECOUNT(expr, oper, val)
功能说明:返回满足某个条件的连续记录的个数,结果作为新的一列追加在每行后面。条件根据参数计算,如果条件为 true 则加 1,条件为 false 则重置为-1,如果数据为 NULL,跳过该条数据。
参数范围:
- oper : "LT" (小于)、"GT"(大于)、"LE"(小于等于)、"GE"(大于等于)、"NE"(不等于)、"EQ"(等于),不区分大小写。
- val : 数值型
返回结果类型:INTEGER。
适用数据类型:数值类型。
嵌套子查询支持:不支持应用在子查询上。
适用于:表和超级表。
使用说明:
- 不能和窗口操作一起使用,例如 interval/state_window/session_window。
STATEDURATION
STATEDURATION(expr, oper, val, unit)
功能说明:返回满足某个条件的连续记录的时间长度,结果作为新的一列追加在每行后面。条件根据参数计算,如果条件为 true 则加上两个记录之间的时间长度(第一个满足条件的记录时间长度记为 0),条件为 false 则重置为-1,如果数据为 NULL,跳过该条数据。
参数范围:
- oper :
'LT'
(小于)、'GT'
(大于)、'LE'
(小于等于)、'GE'
(大于等于)、'NE'
(不等于)、'EQ'
(等于),不区分大小写,但需要用''
包括。 - val : 数值型
- unit : 时间长度的单位,可取值时间单位: 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。如果省略,默认为当前数据库精度。
返回结果类型:INTEGER。
适用数据类型:数值类型。
嵌套子查询支持:不支持应用在子查询上。
适用于:表和超级表。
使用说明:
- 不能和窗口操作一起使用,例如 interval/state_window/session_window。
TWA
TWA(expr)
功能说明:时间加权平均函数。统计表中某列在一段时间内的时间加权平均。对于存在复合主键的表的查询,若时间戳相同的数据存在多条,则只有对应的复合主键最小的数据参与运算。
返回数据类型:DOUBLE。
适用数据类 型:数值类型。
适用于:表和超级表。
系统信息函数
DATABASE
SELECT DATABASE();
说明:返回当前登录的数据库。如果登录的时候没有指定默认数据库,且没有使用USE命令切换数据库,则返回NULL。
CLIENT_VERSION
SELECT CLIENT_VERSION();
说明:返回客户端版本。
SERVER_VERSION
SELECT SERVER_VERSION();
说明:返回服务端版本。
SERVER_STATUS
SELECT SERVER_STATUS();
说明:检测服务端是否所有 dnode 都在线,如果是则返回成功,否则返回无法建立连接的错误。如果想要查询集群的状态,推荐使用 SHOW CLUSTER ALIVE;
, 与 SELECT SERVER_STATUS();
不同,当集群中的部分节点不可用时,它不会返回错误,而是返回不同的状态码,详见:SHOW CLUSTER ALIVE
CURRENT_USER
SELECT CURRENT_USER();
说明:获取当前用户。
Geometry 函数
Geometry 输入函数:
ST_GeomFromText
ST_GeomFromText(VARCHAR WKT expr)
功能说明:根据 Well-Known Text (WKT) 表示从指定的几何值创建几何数据。
返回值类型:GEOMETRY
适用数据类型:VARCHAR
适用表类型:标准表和超表
使用说明:输入可以是 WKT 字符串之一,例如点(POINT)、线串(LINESTRING)、多边形(POLYGON)、多点集(MULTIPOINT)、多线串(MULTILINESTRING)、多多边形(MULTIPOLYGON)、几何集合(GEOMETRYCOLLECTION)。输出是以二进制字符串形式定义的 GEOMETRY 数据类型。
Geometry 输出函数:
ST_AsText
ST_AsText(GEOMETRY geom)
功能说明:从几何数据中返回指定的 Well-Known Text (WKT) 表示。
返回值类型:VARCHAR
适用数据类型:GEOMETRY
适用表类型:标准表和超表
使用说明:输出可以是 WKT 字符串之一,例如点(POINT)、线串(LINESTRING)、多边形(POLYGON)、多点集(MULTIPOINT)、多线串(MULTILINESTRING)、多多边形(MULTIPOLYGON)、几何集合(GEOMETRYCOLLECTION)。
Geometry 关系函数:
ST_Intersects
ST_Intersects(GEOMETRY geomA, GEOMETRY geomB)
##功能说明**:比较两个几何对象,并在它们相交时返回 true。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:如果两个几何对象有任何一个共享点,则它们相交。
ST_Equals
ST_Equals(GEOMETRY geomA, GEOMETRY geomB)
功能说明:如果给定的几何对象是"空间相等"的,则返回 TRUE。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:"空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true,并且点的顺序可能不同,但表示相同的几何结构。
ST_Touches
ST_Touches(GEOMETRY geomA, GEOMETRY geomB)
功能说明:如果 A 和 B 相交,但它们的内部不相交,则返回 TRUE。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:A 和 B 至少有一个公共点,并且这些公共点位于至少一个边界中。对于点/点输入,关系始终为 FALSE,因为点没有边界。
ST_Covers
ST_Covers(GEOMETRY geomA, GEOMETRY geomB)
功能说明:如果 B 中的每个点都位于几何形状 A 内部(与内部或边界相交),则返回 TRUE。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:A 包含 B 意味着 B 中的没有点位于 A 的外部(在外部)。
ST_Contains
ST_Contains(GEOMETRY geomA, GEOMETRY geomB)
功能说明:如果 A 包含 B,描述:如果几何形状 A 包含几何形状 B,则返回 TRUE。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:A 包含 B 当且仅当 B 的所有点位于 A 的内部(即位于内部或边界上)(或等效地,B 的没有点位于 A 的外部),并且 A 和 B 的内部至少有一 个公共点。
ST_ContainsProperly
ST_ContainsProperly(GEOMETRY geomA, GEOMETRY geomB)
功能说明:如果 B 的每个点都位于 A 内部,则返回 TRUE。
返回值类型:BOOL
适用数据类型:GEOMETRY,GEOMETRY
适用表类型:标准表和超表
使用说明:B 的 没有点位于 A 的边界或外部。