diff --git a/docs/zh/14-reference/03-taos-sql/10-function.md b/docs/zh/14-reference/03-taos-sql/10-function.md index 529b11503e..d02d60571a 100644 --- a/docs/zh/14-reference/03-taos-sql/10-function.md +++ b/docs/zh/14-reference/03-taos-sql/10-function.md @@ -25,7 +25,7 @@ ABS(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -43,7 +43,7 @@ ACOS(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -61,7 +61,7 @@ ASIN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -80,7 +80,7 @@ ATAN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -97,11 +97,11 @@ CEIL(expr) **适用数据类型**:数值类型。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**使用说明**: 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 +**使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 #### COS @@ -117,7 +117,7 @@ COS(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -144,7 +144,7 @@ LOG(expr1[, expr2]) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -163,7 +163,7 @@ POW(expr1, expr2) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -183,17 +183,17 @@ ROUND(expr[, digits]) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `expr` 或 `digits` 为 NULL,返回 NULL。 - 若指定了`digits`,则会保留 `digits` 位小数,默认为 0。 -- 若输入值是 INTEGER 类型, 无论 `digits` 值为多少,都只会返回 INTEGER 类型,不会保留小数。 +- 若输入值是 INTEGER 类型,无论 `digits` 值为多少,都只会返回 INTEGER 类型,不会保留小数。 - `digits` 大于零表示对小数位进行操作,四舍五入到 `digits` 位小数。若小数位数小于 `digits` 位,不进行四舍五入操作,直接返回。 - `digits` 小于零表示丢掉小数位,并将数字四舍五入到小数点左侧 `digits` 位。若小数点左侧的位数小于 `digits`位,返回 0。 - 由于暂未支持 DECIMAL 类型,所以该函数会用 DOUBLE 和 FLOAT 来表示包含小数的结果,但是 DOUBLE 和 FLOAT 是有精度上限的,当位数太多时使用该函数可能没有意义。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 -- `digits` 从 ver-3.3.3.0 开始支持。 +- `digits` 从 3.3.3.0 版本开始支持。 **举例**: ```sql @@ -222,7 +222,7 @@ SIN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -240,7 +240,7 @@ SQRT(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -258,7 +258,7 @@ TAN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**:只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 @@ -269,7 +269,7 @@ PI() **功能说明**:返回圆周率 π 的值。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -277,7 +277,7 @@ PI() **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - π ≈ 3.141592653589793。 @@ -298,7 +298,7 @@ TRUNCATE(expr, digits) **功能说明**:获得指定字段按照指定位数截断的值。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与 `expr` 字段的原始数据类型一致。 @@ -308,7 +308,7 @@ TRUNCATE(expr, digits) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `expr` 或 `digits` 为 NULL,返回 NULL。 @@ -338,7 +338,7 @@ EXP(expr) ``` **功能说明**:返回 e(自然对数的底)的指定乘方后的值。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -346,7 +346,7 @@ EXP(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr` 为 NULL,返回 NULL。 @@ -367,7 +367,7 @@ LN(expr) **功能说明**:返回指定参数的自然对数。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -375,7 +375,7 @@ LN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr` 为 NULL,返回 NULL。 @@ -397,7 +397,7 @@ MOD(expr1, expr2) **功能说明**:计算 expr1 % expr2 的结果。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -405,7 +405,7 @@ MOD(expr1, expr2) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr2` 为 0 则返回 NULL。 @@ -432,7 +432,7 @@ RAND([seed]) **功能说明**:返回一个从0到1均匀分布的随机数。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -441,7 +441,7 @@ RAND([seed]) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果指定了 `seed` 值,那么将会用指定的 `seed` 作为随机种子,确保生成的随机数序列具有确定性。 @@ -477,7 +477,7 @@ SIGN(expr) **功能说明**:返回指定参数的符号。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与指定字段的原始数据类型一致。 @@ -485,13 +485,13 @@ SIGN(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 如果 `expr` 为负,返回 -1 , -- 如果 `expr` 为正,返回 1 , -- 如果 `expr` 为 0 ,返回 0 。 -- 如果 `expr` 为 NULL ,返回 NULL 。 +- 如果 `expr` 为负,返回 -1。 +- 如果 `expr` 为正,返回 1。 +- 如果 `expr` 为 0 ,返回 0。 +- 如果 `expr` 为 NULL ,返回 NULL。 - 只能与普通列,选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。 **举例**: @@ -519,7 +519,7 @@ DEGREES(expr) **功能说明**:计算指定参数由弧度值转为角度后的值。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -527,7 +527,7 @@ DEGREES(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr` 为 NULL,则返回 NULL。 @@ -549,7 +549,7 @@ RADIANS(expr) **功能说明**:计算指定参数由角度值转为弧度后的值。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:DOUBLE。 @@ -557,7 +557,7 @@ RADIANS(expr) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr` 为 NULL,则返回 NULL。 @@ -585,18 +585,18 @@ CHAR_LENGTH(expr) **返回结果类型**:BIGINT。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 与 `LENGTH()` 函数不同在于,对于多字节字符,比如中文字符, `CHAR_LENGTH()` 函数会将其算做一个字符,长度为 1,而 `LENGTH()` 会计算其字节数,长度为 3。比如 `CHAR_LENGTH('你好') = 2`, `LENGTH('你好') = 6`。 +- 与 `LENGTH()` 函数不同在于,对于多字节字符,比如中文字符,`CHAR_LENGTH()` 函数会将其算做一个字符,长度为 1,而 `LENGTH()` 会计算其字节数,长度为 3。比如 `CHAR_LENGTH('你好') = 2`,`LENGTH('你好') = 6`。 - 如果 `expr` 为 NULL,返回 NULL。 **举例**: @@ -620,13 +620,13 @@ CONCAT(expr1, expr2 [, expr] ... ) **功能说明**:字符串连接函数。 -**返回结果类型**:如果所有参数均为 VARCHAR 类型,则结果类型为 VARCHAR。如果参数包含NCHAR类型,则结果类型为NCHAR。如果参数包含NULL值,则输出值为NULL。 +**返回结果类型**:如果所有参数均为 VARCHAR 类型,则结果类型为 VARCHAR。如果参数包含 NCHAR 类型,则结果类型为 NCHAR。如果参数包含NULL值,则输出值为 NULL。 -**适用数据类型**:VARCHAR, NCHAR。 该函数最小参数个数为2个,最大参数个数为8个。 +**适用数据类型**:VARCHAR、NCHAR。该函数最小参数个数为 2 个,最大参数个数为 8 个。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### CONCAT_WS @@ -637,13 +637,13 @@ CONCAT_WS(separator_expr, expr1, expr2 [, expr] ...) **功能说明**:带分隔符的字符串连接函数。 -**返回结果类型**:如果所有参数均为VARCHAR类型,则结果类型为VARCHAR。如果参数包含NCHAR类型,则结果类型为NCHAR。如果参数包含NULL值,则输出值为NULL。 +**返回结果类型**:如果所有参数均为 VARCHAR 类型,则结果类型为 VARCHAR。如果参数包含 NCHAR 类型,则结果类型为 NCHAR。如果参数包含 NULL 值,则输出值为 NULL。 -**适用数据类型**:VARCHAR, NCHAR。 该函数最小参数个数为3个,最大参数个数为9个。 +**适用数据类型**:VARCHAR、NCHAR。该函数最小参数个数为 3 个,最大参数个数为 9 个。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### LENGTH @@ -656,11 +656,11 @@ LENGTH(expr) **返回结果类型**:BIGINT。 -**适用数据类型**:VARCHAR, NCHAR, VARBINARY。 +**适用数据类型**:VARCHAR、NCHAR、VARBINARY。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### LOWER @@ -673,11 +673,11 @@ LOWER(expr) **返回结果类型**:与输入字段的原始类型相同。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### LTRIM @@ -690,11 +690,11 @@ LTRIM(expr) **返回结果类型**:与输入字段的原始类型相同。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### RTRIM @@ -707,11 +707,11 @@ RTRIM(expr) **返回结果类型**:与输入字段的原始类型相同。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### TRIM ```sql @@ -719,29 +719,29 @@ TRIM([{LEADING | TRAILING | BOTH} [remstr] FROM] expr) TRIM([remstr FROM] expr) ``` -**功能说明**:返回去掉了所有 remstr 前缀或后缀的字符串 epxr 。 +**功能说明**:返回去掉了所有 remstr 前缀或后缀的字符串 epxr。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与输入字段 epxr 的原始类型相同。 **适用数据类型**: -- remstr:VARCHAR,NCHAR。 -- epxr:VARCHAR,NCHAR。 +- remstr:VARCHAR、NCHAR。 +- epxr:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 第一个可选变量[LEADING | BOTH | TRAILING]指定要剪裁字符串的哪一侧: +- 第一个可选变量 [LEADING | BOTH | TRAILING] 指定要剪裁字符串的哪一侧: - LEADING 将移除字符串开头的指定字符。 - TRAILING 将移除字符串末尾的指定字符。 - BOTH(默认值)将移除字符串开头和末尾的指定字符。 -- 第二个可选变量[remstr]指定要裁剪掉的字符串: - - 如果不指定 remstr ,默认裁剪空格。 - - remstr 可以指定多个字符,如trim('ab' from 'abacd') ,此时会将 'ab' 看做一个整体来裁剪,得到裁剪结果 'acd'。 -- 若 expr 为 NULL, 返回 NULL。 +- 第二个可选变量 [remstr] 指定要裁剪掉的字符串: + - 如果不指定 remstr,默认裁剪空格。 + - remstr 可以指定多个字符,如 trim('ab' from 'abacd') ,此时会将 'ab' 看做一个整体来裁剪,得到裁剪结果 'acd'。 +- 若 expr 为 NULL,返回 NULL。 - 该函数是多字节安全的。 **举例**: @@ -778,13 +778,13 @@ SUBSTRING/SUBSTR(expr FROM pos [FOR len]) **返回结果类型**:与输入字段 `expr` 的原始类型相同。 **适用数据类型**: -- `expr`:VARCHAR,NCHAR。 +- `expr`:VARCHAR、NCHAR。 - `pos`:整数类型。 - `len`:整数类型。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `pos` 为正数,则返回的结果为 `expr` 从左到右开始数 `pos` 位置开始的右侧的子串。 @@ -794,8 +794,8 @@ SUBSTRING/SUBSTR(expr FROM pos [FOR len]) - 若 `len` 小于 1,返回空串。 - `pos` 是 1-base 的,若 `pos` 为 0,返回空串。 - 若 `pos` + `len` 大于 `len(expr)`,返回从 `pos` 开始到字符串结尾的子串,等同于执行 `substring(expr, pos)`。 -- `SUBSTRING` 函数等价于 `SUBSTR`, 从 ver-3.3.3.0 开始支持。 -- `SUBSTRING/SUBSTR(expr FROM pos [FOR len])` 语法从 ver-3.3.3.0 开始支持。 +- `SUBSTRING` 函数等价于 `SUBSTR`,从 3.3.3.0 版本开始支持。 +- `SUBSTRING/SUBSTR(expr FROM pos [FOR len])` 语法从 3.3.3.0 版本开始支持。 **举例**: ```sql @@ -832,18 +832,18 @@ SUBSTRING_INDEX(expr, delim, count) **功能说明**:返回字符串 `expr` 在出现指定次数分隔符的位置截取的子串。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与输入字段 `expr` 的原始类型相同。 **适用数据类型**: -- `expr`:VARCHAR,NCHAR。 -- `delim`:VARCHAR, NCHAR。 +- `expr`:VARCHA、 NCHAR。 +- `delim`:VARCHAR、NCHAR。 - `count`:INTEGER。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `count` 为正数,则返回的结果为 `expr` 从左到右开始数第 `count` 次 出现 `delim` 的位置左侧的字符串。 @@ -874,11 +874,11 @@ UPPER(expr) **返回结果类型**:与输入字段的原始类型相同。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### CHAR ```sql @@ -887,7 +887,7 @@ CHAR(expr1 [, expr2] [, epxr3] ...) **功能说明**:将输入参数当作整数,并返回这些整数在 ASCII 编码中对应的字符。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:VARCHAR。 @@ -895,10 +895,10 @@ CHAR(expr1 [, expr2] [, epxr3] ...) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 输入的值超过 255 会被转化成多字节的结果,如 `CHAR(256)` 等同于 `CHAR(1,0)`, `CHAR(256 * 256)` 等同于 `CHAR(1,0,0)`。 +- 输入的值超过 255 会被转化成多字节的结果,如 `CHAR(256)` 等同于 `CHAR(1,0)`,`CHAR(256 * 256)` 等同于 `CHAR(1,0,0)`。 - 输入参数的 NULL 值会被跳过。 - 输入参数若为字符串类型,会将其转换为数值类型处理。 - 若输入的参数对应的字符为不可打印字符,返回值中仍有该参数对应的字符,但是可能无法显示出来。 @@ -934,15 +934,15 @@ ASCII(expr) **功能说明**:返回字符串第一个字符的 ASCII 码。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果数据类型**:BIGINT。 -**适用数据类型**:VARCHAR, NCHAR。 +**适用数据类型**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 如果 `expr` 为 NULL,返回 NULL。 @@ -963,17 +963,17 @@ POSITION(expr1 IN expr2) **功能说明**:计算字符串 `expr1` 在字符串 `expr2` 中的位置。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:BIGINT。 **适用数据类型**: -- `expr1`:VARCHAR, NCHAR。 -- `expr2`:VARCHAR, NCHAR。 +- `expr1`:VARCHAR、NCHAR。 +- `expr2`:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `expr1` 或 `expr2` 为 NULL,返回 NULL。 @@ -1007,18 +1007,18 @@ REPLACE(expr, from_str, to_str) ``` **功能说明**:将字符串中的 `from_str` 全部替换为 `to_str`。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与输入字段 `expr` 的原始类型相同。 **适用数据类型**: -- `expr`:VARCHAR, NCHAR。 -- `from_str`:VARCHAR, NCHAR。 -- `to_str`:VARCHAR, NCHAR。 +- `expr`:VARCHAR、NCHAR。 +- `from_str`:VARCHAR、NCHAR。 +- `to_str`:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 该函数是大小写敏感的。 @@ -1039,17 +1039,17 @@ REPEAT(expr, count) ``` **功能说明**:返回将字符串重复指定次数得到的字符串。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:与输入字段 `expr` 的原始类型相同。 **适用数据类型**: -- `expr`: VARCHAR,NCHAR。 +- `expr`:VARCHAR、NCHAR。 - `count`:INTEGER。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `count < 1`,返回空串。 @@ -1085,15 +1085,15 @@ CAST(expr AS type_name) **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 对于不能支持的类型转换会直接报错。 - 对于类型支持但某些值无法正确转换的情况,对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况: - 1)字符串类型转换数值类型时可能出现的无效字符情况,例如"a"可能转为0,但不会报错。 - 2)转换到数值类型时,数值大于type_name可表示的范围时,则会溢出,但不会报错。 - 3)转换到字符串类型时,如果转换后长度超过type_name中指定的长度,则会截断,但不会报错。 + 1)字符串类型转换数值类型时可能出现的无效字符情况,例如 "a" 可能转为 0,但不会报错。 + 2)转换到数值类型时,数值大于 type_name 可表示的范围时,则会溢出,但不会报错。 + 3)转换到字符串类型时,如果转换后长度超过 type_name 中指定的长度,则会截断,但不会报错。 #### TO_ISO8601 @@ -1105,16 +1105,16 @@ TO_ISO8601(expr [, timezone]) **返回结果数据类型**:VARCHAR 类型。 -**适用数据类型**:INTEGER, TIMESTAMP。 +**适用数据类型**:INTEGER、TIMESTAMP。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- timezone 参数允许输入的时区格式为: [z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如,TO_ISO8601(1, "+00:00")。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- timezone 参数允许输入的时区格式为:[z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如 TO_ISO8601(1, "+00:00")。 +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 #### TO_JSON @@ -1123,15 +1123,15 @@ TO_ISO8601(expr [, timezone]) TO_JSON(str_literal) ``` -**功能说明**: 将字符串常量转换为 JSON 类型。 +**功能说明**:将字符串常量转换为 JSON 类型。 -**返回结果数据类型**: JSON。 +**返回结果数据类型**:JSON。 -**适用数据类型**: JSON 字符串,形如 '\{ "literal" : literal }'。'\{}'表示空值。键必须为字符串字面量,值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal中不支持转义符。 +**适用数据类型**:JSON 字符串,形如 '\{ "literal" : literal }'。'\{}' 表示空值。键必须为字符串字面量,值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal 中不支持转义符。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 #### TO_UNIXTIMESTAMP @@ -1147,9 +1147,9 @@ return_timestamp: { **功能说明**:将日期时间格式的字符串转换成为时间戳。 -**返回结果数据类型**:BIGINT, TIMESTAMP。 +**返回结果数据类型**:BIGINT、TIMESTAMP。 -**应用字段**:VARCHAR, NCHAR。 +**应用字段**:VARCHAR、NCHAR。 **嵌套子查询支持**:适用于内层查询和外层查询。 @@ -1159,7 +1159,7 @@ return_timestamp: { - 输入的日期时间字符串须符合 ISO8601/RFC3339 标准,无法转换的字符串格式将返回 NULL。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 -- return_timestamp 指定函数返回值是否为时间戳类型,设置为1时返回 TIMESTAMP 类型,设置为0时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 +- return_timestamp 指定函数返回值是否为时间戳类型,设置为 1 时返回 TIMESTAMP 类型,设置为 0 时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 #### TO_CHAR @@ -1167,17 +1167,17 @@ return_timestamp: { TO_CHAR(ts, format_str_literal) ``` -**功能说明**: 将timestamp类型按照指定格式转换为字符串 +**功能说明**:将timestamp类型按照指定格式转换为字符串。 -**版本**: ver-3.2.2.0 +**使用说明**:ver-3.2.2.0 -**返回结果数据类型**: VARCHAR +**返回结果数据类型**:VARCHAR。 -**应用字段**: TIMESTAMP +**适用数据类型**:TIMESTAMP。 -**嵌套子查询支持**: 适用于内层查询和外层查询 +**嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表 +**适用于**:表和超级表。 **支持的格式** @@ -1185,42 +1185,42 @@ TO_CHAR(ts, format_str_literal) | ------------------- | ----------------------------------------- | ------------------------- | | 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 | | +| 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` 可以互换. -- 推荐在时间格式中带时区信息,如果不带则默认输出的时区为服务端或客户端所配置的时区. -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +**使用说明**: +- `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 @@ -1228,36 +1228,36 @@ TO_CHAR(ts, format_str_literal) TO_TIMESTAMP(ts_str_literal, format_str_literal) ``` -**功能说明**: 将字符串按照指定格式转化为时间戳. +**功能说明**:将字符串按照指定格式转化为时间戳。 -**版本**: ver-3.2.2.0 +**使用说明**:ver-3.2.2.0 -**返回结果数据类型**: TIMESTAMP +**返回结果数据类型**:TIMESTAMP。 -**应用字段**: VARCHAR +**适用数据类型**:VARCHAR。 -**嵌套子查询支持**: 适用于内层查询和外层查询 +**嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表 +**适用于**:表和超级表。 -**支持的格式**: 与`to_char`相同 +**使用说明**:与 `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`. +**使用说明**: +- 若 `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、TODAY 和 TIMEZONE,在一条 SQL 语句中不论出现多少次都只会被计算一次。 #### NOW @@ -1277,7 +1277,7 @@ NOW() **使用说明**: -- 支持时间加减操作,如 NOW() + 1s, 支持的时间单位如下: +- 支持时间加减操作,如 NOW() + 1s,支持的时间单位如下: b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 @@ -1293,22 +1293,22 @@ TIMEDIFF(expr1, expr2 [, time_unit]) **返回结果类型**:BIGINT。 **适用数据类型**: -- `expr1`:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 -- `expr2`:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 +- `expr1`:表示时间戳的 BIGIN、 TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 +- `expr2`:表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 - `time_unit`:见使用说明。 -- ver-3.3.3.0 之前该函数结果为时间戳 `expr1` 和 `expr2` 的差值的绝对值,结果为正数。 +- 3.3.3.0 版本之前该函数结果为时间戳 `expr1` 和 `expr2` 的差值的绝对值,结果为正数。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 支持的时间单位 `time_unit` 如下: 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。 -- 如果时间单位 `time_unit` 未指定, 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 +- 支持的时间单位 `time_unit` 包括 1b(纳秒)、1u(微秒)、1a(毫秒)、1s(秒)、1m(分)、1h(小时)、1d(天)、1w(周)。 +- 如果时间单位 `time_unit` 未指定,返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 - 输入包含不符合时间日期格式的字符串则返回 NULL。 - `expr1` 或 `expr2` 为 NULL,返回 NULL。 - `time_unit` 为 NULL,等同于未指定时间单位。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 **举例**: ```sql @@ -1338,23 +1338,21 @@ use_current_timezone: { **返回结果数据类型**:TIMESTAMP。 -**应用字段**:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 +**应用字段**:表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 **适用于**:表和超级表。 **使用说明**: -- 支持的时间单位 time_unit 如下: - 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。 +- 支持的时间单位 time_unit 包括 1b(纳秒)、1u(微秒)、1a(毫秒)、1s(秒)、1m(分)、,1h(小时)、1d(天)、1w(周)。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 - 输入包含不符合时间日期格式的字符串则返回 NULL。 -- 当使用 1d/1w 作为时间单位对时间戳进行截断时, 可通过设置 use_current_timezone 参数指定是否根据当前时区进行截断处理。 +- 当使用 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'。 + 例如客户端所配置时区为 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 时间戳始于星期四, - 因此所有截断后的日期都是星期四。 +- 当将时间值截断到一周(1w)时,timetruncate 的计算是基于 Unix 时间戳(1970年1月1日00:00:00 UTC)进行的。Unix 时间戳始于星期四,因此所有截断后的日期都是星期四。 #### TIMEZONE @@ -1367,7 +1365,7 @@ TIMEZONE() **返回结果数据类型**:VARCHAR。 -**应用字段**:无 +**应用字段**:无。 **适用于**:表和超级表。 @@ -1388,8 +1386,8 @@ TODAY() **使用说明**: -- 支持时间加减操作,如 TODAY() + 1s, 支持的时间单位如下: - b(纳秒),u(微秒),a(毫秒),s(秒),m(分),h(小时),d(天),w(周)。 +- 支持时间加减操作,如 TODAY() + 1s,支持的时间单位如下: + b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 #### WEEK @@ -1398,22 +1396,22 @@ WEEK(expr [, mode]) ``` **功能说明**:返回输入日期的周数。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:BIGINT。 **适用数据类型**: -- `expr`:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 -- `mode`:0 - 7 之间的整数。 +- `expr`:表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 +- `mode`:0-7 之间的整数。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 若 `expr` 为 NULL,返回 NULL。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. -- `mode` 用来指定一周是从周日开始还是周一开始,以及指定返回值范围是 1 - 53 还是 0 - 53。下表详细描述不同的 mode 对应的计算方法: +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 +- `mode` 用来指定一周是从周日开始还是周一开始,以及指定返回值范围是 1-53 还是 0-53。下表详细描述不同的 mode 对应的计算方法: | Mode | 每周的第一天 | 返回值范围 | 第 1 周的计算方法 | | ---- | ------ | ------ | ------------------ | @@ -1425,12 +1423,12 @@ WEEK(expr [, mode]) | 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。 +- 当返回值范围为 0-53 时,第 1 周之前的日期为第 0 周。 +- 当返回值范围为 1-53 时,第 1 周之前的日期为上一年的最后一周。 +- 以 `2000-01-01` 为例, + - 在 `mode=0`时返回值为 `0`,因为该年第一个周日为 `2000-01-02`,从 `2000-01-02` 起才是第一周,所以 `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-53,所以 `2000-01-01` 算做上一年的最后一周,即 1999 年的第 52 周,返回 52。 **举例**: ```sql @@ -1461,20 +1459,20 @@ WEEKOFYEAR(expr) ``` **功能说明**:返回输入日期的周数。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:BIGINT。 -**适用数据类型**:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 +**适用数据类型**:表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 等同于`WEEK(expr, 3)`,即在每周第一天是周一,返回值范围为 1 - 53,第一个包含四天及以上的周为第 1 周的条件下判断输入日期的周数。 +- 等同于`WEEK(expr, 3)`,即在每周第一天是周一,返回值范围为 1-53,第一个包含四天及以上的周为第 1 周的条件下判断输入日期的周数。 - 若 `expr` 为 NULL,返回 NULL。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 **举例**: ```sql @@ -1490,20 +1488,20 @@ WEEKDAY(expr) ``` **功能说明**:返回输入日期是周几。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:BIGINT。 -**适用数据类型**:表示 表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 +**适用数据类型**:表示 表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: - 返回值 0 代表周一,1 代表周二 ... 6 代表周日。 - 若 `expr` 为 NULL,返回 NULL。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 **举例**: ```sql @@ -1519,20 +1517,20 @@ DAYOFWEEK(expr) ``` **功能说明**:返回输入日期是周几。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回结果类型**:BIGINT。 -**适用数据类型**:表示时间戳的 BIGINT, TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR, NCHAR 类型。 +**适用数据类型**:表示时间戳的 BIGINT、TIMESTAMP 类型,或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 **嵌套子查询支持**:适用于内层查询和外层查询。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **使用说明**: -- 返回值 1 代表周日,2 代表周一 ... 7 代表周六 +- 返回值 1 代表周日,2 代表周一 ... 7 代表周六。 - 若 `expr` 为 NULL,返回 NULL。 -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. +- 输入时间戳的精度由所查询表的精度确定,若未指定表,则精度为毫秒。 **举例**: ```sql @@ -1562,16 +1560,16 @@ algo_type: { **功能说明**:统计表/超级表中指定列的值的近似百分比分位数,与 PERCENTILE 函数相似,但是返回近似结果。 -**返回数据类型**: DOUBLE。 +**返回数据类型**:DOUBLE。 **适用数据类型**:数值类型。 **适用于**:表和超级表。 **说明**: -- p值范围是[0,100],当为0时等同于MIN,为100时等同于MAX。 -- algo_type 取值为 "default" 或 "t-digest"。 输入为 "default" 时函数使用基于直方图算法进行计算。输入为 "t-digest" 时使用t-digest算法计算分位数的近似结果。如果不指定 algo_type 则使用 "default" 算法。 -- "t-digest"算法的近似结果对于输入数据顺序敏感,对超级表查询时不同的输入排序结果可能会有微小的误差。 +- p 值范围是 [0,100],当为 0 时等同于 MIN,为 100 时等同于 MAX。 +- algo_type 取值为 "default" 或 "t-digest"。输入为 "default" 时函数使用基于直方图算法进行计算。输入为 "t-digest" 时使用t-digest算法计算分位数的近似结果。如果不指定 algo_type 则使用 "default" 算法。 +- "t-digest" 算法的近似结果对于输入数据顺序敏感,对超级表查询时不同的输入排序结果可能会有微小的误差。 ### AVG @@ -1602,7 +1600,7 @@ COUNT({* | expr}) **适用于**:表和超级表。 -**使用说明**: +**使用说明**: - 可以使用星号(\*)来替代具体的字段,使用星号(\*)返回全部记录数量。 - 如果统计字段是具体的列,则返回该列中非 NULL 值的记录数量。 @@ -1620,12 +1618,12 @@ ELAPSED(ts_primary_key [, time_unit]) **适用数据类型**:TIMESTAMP。 -**适用于**: 表,超级表,嵌套查询的外层查询 +**适用于**:表、超级表、嵌套查询的外层查询。 **说明**: - ts_primary_key 参数只能是表的第一列,即 TIMESTAMP 类型的主键列。 - 按 time_unit 参数指定的时间单位返回,最小是数据库的时间分辨率。time_unit 参数未指定时,以数据库的时间分辨率为时间单位。支持的时间单位 time_unit 如下: - 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。 + 1b(纳秒)、1u(微秒)、1a(毫秒)、1s(秒)、1m(分)、1h(小时)、1d(天)、1w(周)。 - 可以和 interval 组合使用,返回每个时间窗口的时间戳差值。需要特别注意的是,除第一个时间窗口和最后一个时间窗口外,中间窗口的时间戳差值均为窗口长度。 - order by asc/desc 不影响差值的计算结果。 - 对于超级表,需要和 group by tbname 子句组合使用,不可以直接使用。 @@ -1642,7 +1640,7 @@ LEASTSQUARES(expr, start_val, step_val) **功能说明**:统计表中某列的值的拟合直线方程。start_val 是自变量初始值,step_val 是自变量的步长值。 -**返回数据类型**:字符串表达式(斜率, 截距)。 +**返回数据类型**:字符串表达式(斜率、截距)。 **适用数据类型**:expr 必须是数值类型。 @@ -1659,7 +1657,7 @@ SPREAD(expr) **返回数据类型**:DOUBLE。 -**适用数据类型**:INTEGER, TIMESTAMP。 +**适用数据类型**:INTEGER、TIMESTAMP。 **适用于**:表和超级表。 @@ -1679,7 +1677,7 @@ STDDEV/STDDEV_POP(expr) **适用于**:表和超级表。 **说明**: -- `STDDEV_POP` 函数等价于 `STDDEV` 函数,从 ver-3.3.3.0 开始支持。 +- `STDDEV_POP` 函数等价于 `STDDEV` 函数,从 3.3.3.0 版本开始支持。 **举例**: ```sql @@ -1704,7 +1702,7 @@ VAR_POP(expr) **功能说明**:统计表中某列的总体方差。 -**版本**: ver-3.3.3.0 +**使用说明**:ver-3.3.3.0 **返回数据类型**:DOUBLE。 @@ -1736,7 +1734,7 @@ SUM(expr) **功能说明**:统计表/超级表中某列的和。 -**返回数据类型**:DOUBLE, BIGINT。 +**返回数据类型**:DOUBLE、BIGINT。 **适用数据类型**:数值类型。 @@ -1772,10 +1770,10 @@ HISTOGRAM(expr,bin_type, bin_description, normalized) **适用数据类型**:数值型字段。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 **详细说明**: -- bin_type 用户指定的分桶类型, 有效输入类型为"user_input“, ”linear_bin", "log_bin"。 +- bin_type 用户指定的分桶类型,有效输入类型为 "user_input"、"linear_bin"、"log_bin"。 - bin_description 描述如何生成分桶区间,针对三种桶类型,分别为以下描述格式(均为 JSON 格式字符串): - "user_input": "[1, 3, 5, 7]" 用户指定 bin 的具体数值。 @@ -1798,7 +1796,7 @@ PERCENTILE(expr, p [, p1] ... ) **功能说明**:统计表中某列的值百分比分位数。 -**返回数据类型**: 该函数最小参数个数为 2 个,最大参数个数为 11 个。可以最多同时返回 10 个百分比分位数。当参数个数为 2 时, 返回一个分位数, 类型为DOUBLE,当参数个数大于 2 时,返回类型为VARCHAR, 格式为包含多个返回值的JSON数组。 +**返回数据类型**:该函数最小参数个数为 2 个,最大参数个数为 11 个。可以最多同时返回 10 个百分比分位数。当参数个数为 2 时,返回一个分位数,类型为DOUBLE,当参数个数大于 2 时,返回类型为VARCHAR,格式为包含多个返回值的JSON数组。 **应用字段**:数值类型。 @@ -1808,7 +1806,7 @@ PERCENTILE(expr, p [, p1] ... ) - *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 percentile(col, 90, 95, 99) FROM table,性能会优于SELECT percentile(col, 90), percentile(col, 95), percentile(col, 99) from table。 ## 选择函数 @@ -1829,10 +1827,10 @@ BOTTOM(expr, k) **适用于**:表和超级表。 -**使用说明**: +**使用说明**: -- *k*值取值范围 1≤*k*≤100; -- 系统同时返回该记录关联的时间戳列; +- *k*值取值范围 1≤*k*≤100。 +- 系统同时返回该记录关联的时间戳列。 - 限制:BOTTOM 函数不支持 FILL 子句。 ### FIRST @@ -1849,10 +1847,10 @@ FIRST(expr) **适用于**:表和超级表。 -**使用说明**: +**使用说明**: -- 如果要返回各个列的首个(时间戳最小)非 NULL 值,可以使用 FIRST(\*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,FIRST(\*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 -- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL; +- 如果要返回各个列的首个(时间戳最小)非 NULL 值,可以使用 FIRST(\*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,FIRST(\*) 只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 +- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL。 - 如果结果集中所有列全部为 NULL 值,则不返回结果。 - 对于存在复合主键的表的查询,若最小时间戳的数据有多条,则只有对应的复合主键最小的数据被返回。 @@ -1867,7 +1865,7 @@ ignore_null_values: { } ``` -**功能说明**:返回指定时间截面指定列的记录值或插值。ignore_null_values 参数的值可以是 0 或 1,为 1 时表示忽略 NULL 值, 缺省值为 0。 +**功能说明**:返回指定时间截面指定列的记录值或插值。ignore_null_values 参数的值可以是 0 或 1,为 1 时表示忽略 NULL 值,缺省值为 0。 **返回数据类型**:同字段类型。 @@ -1881,16 +1879,16 @@ ignore_null_values: { - INTERP 的输入数据为指定列的数据,可以通过条件语句(where 子句)来对原始列数据进行过滤,如果没有指定过滤条件则输入为全部数据。 - INTERP SQL 查询需要同时与 RANGE,EVERY 和 FILL 关键字一起使用;流计算不能使用 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 根据 EVERY(time_unit) 字段来确定输出时间范围内的结果条数,即从 timestamp1 开始每隔固定长度的时间(time_unit 值)进行插值,time_unit 可取值时间单位:1a(毫秒),1s(秒),1m(分),1h(小时),1d(天),1w(周)。例如 EVERY(500a) 将对于指定数据每500毫秒间隔进行一次插值。 - INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值。关于 FILL 子句如何使用请参考 [FILL 子句](../distinguished/#fill-子句) -- INTERP 可以在 RANGE 字段中只指定唯一的时间戳对单个时间点进行插值,在这种情况下,EVERY 字段可以省略。例如:SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00') FILL(linear). -- INTERP 作用于超级表时, 会将该超级表下的所有子表数据按照主键列排序后进行插值计算,也可以搭配 PARTITION BY tbname 使用,将结果强制规约到单个时间线。 +- 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 对于带复合主键的表的查询,若存在相同时间戳的数据,则只有对应的复合主键最小的数据参与运算。 -- INTERP 查询支持 NEAR FILL 模式, 即当需要 FILL 时, 使用距离当前时间点最近的数据进行插值, 当前后时间戳与当前时间断面一样近时, FILL 前一行的值. 此模式在流计算中和窗口查询中不支持。例如: SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', '2023-01-01 00:10:00') FILL(NEAR)(3.3.4.9 版本及以后支持)。 -- INTERP 只有在使用 FILL PREV/NEXT/NEAR 模式时才可以使用伪列 `_irowts_origin`。`_irowts_origin`在 3.3.4.9 版本及以后支持。 -- INTERP `RANGE`子句从3.3.4.9版本开始支持时间范围的扩展, 如`RANGE('2023-01-01 00:00:00', 10s)`表示只能使用时间点 '2023-01-01 00:00:00' 周边 10s 内的数据进行插值, FILL PREV/NEXT/NEAR 分别表示从时间点开始向前/向后/前后在时间范围内查找数据, 若时间点周边在指定时间范围内没有数据, 则使用 FILL 指定的默认值进行插值, 因此此时 FILL 子句必须同时指定默认值。例如: SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', 10s) FILL(PREV, 1)。从3.3.6.0版本开始支持时间区间和时间范围的组合,对于时间区间内的每个断面进行插值时都需要满足时间范围的要求,在此之前的版本仅支持时间点和时间范围的组合。时间范围的值域规则与 EVERY 类似, 单位不能是年或月, 值必须大于 0, 不能带引号。使用该扩展时, 不支持除 FILL PREV/NEXT/NEAR 外的其他 FILL 模式。 +- INTERP 查询支持 NEAR FILL 模式,即当需要 FILL 时,使用距离当前时间点最近的数据进行插值,当前后时间戳与当前时间断面一样近时,FILL 前一行的值。此模式在流计算中和窗口查询中不支持。例如 SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', '2023-01-01 00:10:00') FILL(NEAR)(3.3.4.9 版本及以后支持)。 +- INTERP 只有在使用 FILL PREV/NEXT/NEAR 模式时才可以使用伪列 `_irowts_origin`。`_irowts_origin` 在 3.3.4.9 版本及以后支持。 +- INTERP `RANGE`子句从 3.3.4.9 版本开始支持时间范围的扩展,如 `RANGE('2023-01-01 00:00:00', 10s)` 表示只能使用时间点 '2023-01-01 00:00:00' 周边 10s 内的数据进行插值,FILL PREV/NEXT/NEAR 分别表示从时间点开始向前/向后/前后在时间范围内查找数据,若时间点周边在指定时间范围内没有数据,则使用 FILL 指定的默认值进行插值,因此此时 FILL 子句必须同时指定默认值。例如 SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', 10s) FILL(PREV, 1)。从 3.3.6.0 版本开始支持时间区间和时间范围的组合,对于时间区间内的每个断面进行插值时都需要满足时间范围的要求,在此之前的版本仅支持时间点和时间范围的组合。时间范围的值域规则与 EVERY 类似,单位不能是年或月,值必须大于 0,不能带引号。使用该扩展时,不支持除 FILL PREV/NEXT/NEAR 外的其他 FILL 模式。 ### LAST @@ -1906,9 +1904,9 @@ LAST(expr) **适用于**:表和超级表。 -**使用说明**: +**使用说明**: -- 如果要返回各个列的最后(时间戳最大)一个非 NULL 值,可以使用 LAST(\*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,LAST(\*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 +- 如果要返回各个列的最后(时间戳最大)一个非 NULL 值,可以使用 LAST(\*) 查询超级表,且 multiResultFunctionStarReturnTags 设置为 0 (默认值) 时,LAST(\*) 只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 - 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL;如果结果集中所有列全部为 NULL 值,则不返回结果。 - 在用于超级表时,时间戳完全一样且同为最大的数据行可能有多个,那么会从中随机返回一条,而并不保证多次运行所挑选的数据行必然一致。 - 对于存在复合主键的表的查询,若最大时间戳的数据有多条,则只有对应的复合主键最大的数据被返回。 @@ -1929,7 +1927,7 @@ LAST_ROW(expr) **适用于**:表和超级表。 **使用说明**: -- 如果要返回各个列的最后一条记录(时间戳最大),可以使用 LAST_ROW(\*);查询超级表,且multiResultFunctionStarReturnTags设置为 0 (默认值) 时,LAST_ROW(\*)只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 +- 如果要返回各个列的最后一条记录(时间戳最大),可以使用 LAST_ROW(\*) 查询超级表,且 multiResultFunctionStarReturnTags 设置为 0 (默认值) 时,LAST_ROW(\*) 只返回超级表的普通列;设置为 1 时,返回超级表的普通列和标签列。 - 在用于超级表时,时间戳完全一样且同为最大的数据行可能有多个,那么会从中随机返回一条,而并不保证多次运行所挑选的数据行必然一致。 - 不能与 INTERVAL 一起使用。 - 与 LAST 函数一样,对于存在复合主键的表的查询,若最大时间戳的数据有多条,则只有对应的复合主键最大的数据被返回。 @@ -1944,12 +1942,12 @@ MAX(expr) **返回数据类型**:同应用的字段。 -**适用数据类型**:数值类型, VARCHAR,NCHAR。 +**适用数据类型**:数值类型、VARCHAR、NCHAR。 **适用于**:表和超级表。 **使用说明**: -- max 函数可以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值,从 ver-3.3.3.0 开始支持,之前的版本不支持字符串参数。 +- max 函数可以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值,从 3.3.3.0 版本开始支持,之前的版本不支持字符串参数。 ### MIN @@ -1961,12 +1959,12 @@ MIN(expr) **返回数据类型**:同应用的字段。 -**适用数据类型**:数值类型, VARCHAR,NCHAR。 +**适用数据类型**:数值类型、VARCHAR、NCHAR。 **适用于**:表和超级表。 **使用说明**: -- min 函数可以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值,从 ver-3.3.3.0 开始支持,之前的版本不支持字符串参数。 +- min 函数可以接受字符串作为输入参数,当输入参数为字符串类型时,返回最大的字符串值,从 3.3.3.0 版本开始支持,之前的版本不支持字符串参数。 ### MODE @@ -1989,13 +1987,13 @@ MODE(expr) SAMPLE(expr, k) ``` -**功能说明**: 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 +**功能说明**:获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 -**返回结果类型**: 同原始数据类型。 +**返回结果类型**:同原始数据类型。 -**适用数据类型**: 全部类型字段。 +**适用数据类型**:全部类型字段。 -**嵌套子查询支持**: 适用于内层查询和外层查询。 +**嵌套子查询支持**:适用于内层查询和外层查询。 **适用于**:表和超级表。 @@ -2023,7 +2021,7 @@ TAIL(expr, k [, offset_rows]) TOP(expr, k) ``` -**功能说明**: 统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。 +**功能说明**:统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。 **返回数据类型**:同应用的字段。 @@ -2031,10 +2029,10 @@ TOP(expr, k) **适用于**:表和超级表。 -**使用说明**: +**使用说明**: -- *k*值取值范围 1≤*k*≤100; -- 系统同时返回该记录关联的时间戳列; +- *k* 取值范围 1≤*k*≤100。 +- 系统同时返回该记录关联的时间戳列。 - 限制:TOP 函数不支持 FILL 子句。 ### UNIQUE @@ -2049,7 +2047,7 @@ UNIQUE(expr) **适用数据类型**:全部类型字段。 -**适用于**: 表和超级表。 +**适用于**:表和超级表。 ## 时序数据特有函数 @@ -2064,18 +2062,18 @@ CSUM(expr) **功能说明**:累加和(Cumulative sum),忽略 NULL 值。 -**返回结果类型**: 输入列如果是整数类型返回值为长整型 (int64_t),浮点数返回值为双精度浮点数(Double)。无符号整数类型返回值为无符号长整型(uint64_t)。 +**返回结果类型**:输入列如果是整数类型返回值为长整型 (int64_t),浮点数返回值为双精度浮点数(Double)。无符号整数类型返回值为无符号长整型(uint64_t)。 **适用数据类型**:数值类型。 -**嵌套子查询支持**: 适用于内层查询和外层查询。 +**嵌套子查询支持**:适用于内层查询和外层查询。 **适用于**:表和超级表。 **使用说明**: - 不支持 +、-、*、/ 运算,如 csum(col1) + csum(col2)。 -- 只能与聚合(Aggregation)函数一起使用。 该函数可以应用在普通表和超级表上。 +- 只能与聚合(Aggregation)函数一起使用。该函数可以应用在普通表和超级表上。 ### DERIVATIVE @@ -2097,9 +2095,9 @@ ignore_negative: { **适用于**:表和超级表。 -**使用说明**: +**使用说明**: -- 可以与选择相关联的列一起使用。 例如: select \_rowts, DERIVATIVE(col1, 1s, 1) from tb1。 +- 可以与选择相关联的列一起使用,例如 select \_rowts, DERIVATIVE(col1, 1s, 1) from tb1。 ### DIFF @@ -2114,29 +2112,29 @@ ignore_option: { } ``` -**功能说明**:统计表中特定列与之前行的当前列有效值之差。 ignore_option 取值为 0|1|2|3 , 可以不填,默认值为 0. -- `0` 表示不忽略(diff结果)负值不忽略 null 值 -- `1` 表示(diff结果)负值作为 null 值 -- `2` 表示不忽略(diff结果)负值但忽略 null 值 -- `3` 表示忽略(diff结果)负值且忽略 null 值 +**功能说明**:统计表中特定列与之前行的当前列有效值之差。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、时间戳及整型数值类型均返回 int64,浮点类型返回 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 结果为对应的算术差值;时间戳类型根据数据库的时间戳精度进行差值计算;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 @@ -2160,13 +2158,13 @@ IRATE(expr) MAVG(expr, k) ``` -**功能说明**: 计算连续 k 个值的移动平均数(moving average)。如果输入行数小于 k,则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 +**功能说明**:计算连续 k 个值的移动平均数(moving average)。如果输入行数小于 k,则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 -**返回结果类型**: DOUBLE。 +**返回结果类型**:DOUBLE。 -**适用数据类型**: 数值类型。 +**适用数据类型**:数值类型。 -**嵌套子查询支持**: 适用于内层查询和外层查询。 +**嵌套子查询支持**:适用于内层查询和外层查询。 **适用于**:表和超级表。 @@ -2186,8 +2184,8 @@ STATECOUNT(expr, oper, val) **参数范围**: -- oper : "LT" (小于)、"GT"(大于)、"LE"(小于等于)、"GE"(大于等于)、"NE"(不等于)、"EQ"(等于),不区分大小写。 -- val : 数值型 +- oper:"LT" (小于)、"GT"(大于)、"LE"(小于等于)、"GE"(大于等于)、"NE"(不等于)、"EQ"(等于),不区分大小写。 +- val:数值型 **返回结果类型**:INTEGER。 @@ -2212,9 +2210,9 @@ STATEDURATION(expr, oper, val, unit) **参数范围**: -- oper : `'LT'` (小于)、`'GT'`(大于)、`'LE'`(小于等于)、`'GE'`(大于等于)、`'NE'`(不等于)、`'EQ'`(等于),不区分大小写,但需要用`''`包括。 -- val : 数值型 -- unit : 时间长度的单位,可取值时间单位: 1b(纳秒), 1u(微秒),1a(毫秒),1s(秒),1m(分),1h(小时),1d(天), 1w(周)。如果省略,默认为当前数据库精度。 +- oper:`'LT'` (小于)、`'GT'`(大于)、`'LE'`(小于等于)、`'GE'`(大于等于)、`'NE'`(不等于)、`'EQ'`(等于),不区分大小写,但需要用`''`包括。 +- val:数值型 +- unit:时间长度的单位,可取值时间单位:1b(纳秒)、1u(微秒)、1a(毫秒)、1s(秒)、1m(分)、1h(小时)、1d(天)、1w(周)。如果省略,默认为当前数据库精度。 **返回结果类型**:INTEGER。 @@ -2226,7 +2224,7 @@ STATEDURATION(expr, oper, val, unit) **使用说明**: -- 不能和窗口操作一起使用,例如 interval/state_window/session_window。 +- 不能和窗口操作一起使用,例如 interval、state_window、session_window。 ### TWA @@ -2252,7 +2250,7 @@ TWA(expr) SELECT DATABASE(); ``` -**说明**:返回当前登录的数据库。如果登录的时候没有指定默认数据库,且没有使用USE命令切换数据库,则返回NULL。 +**说明**:返回当前登录的数据库。如果登录的时候没有指定默认数据库,且没有使用 USE 命令切换数据库,则返回 NULL。 ### CLIENT_VERSION @@ -2277,7 +2275,7 @@ SELECT SERVER_VERSION(); SELECT SERVER_STATUS(); ``` -**说明**:检测服务端是否所有 dnode 都在线,如果是则返回成功,否则返回无法建立连接的错误。如果想要查询集群的状态,推荐使用 `SHOW CLUSTER ALIVE;`, 与 `SELECT SERVER_STATUS();` 不同,当集群中的部分节点不可用时,它不会返回错误,而是返回不同的状态码,详见:[SHOW CLUSTER ALIVE](https://docs.taosdata.com/reference/taos-sql/show/#show-cluster-alive) +**说明**:检测服务端是否所有 dnode 都在线,如果是则返回成功,否则返回无法建立连接的错误。如果想要查询集群的状态,推荐使用 `SHOW CLUSTER ALIVE;`,与 `SELECT SERVER_STATUS();` 不同,当集群中的部分节点不可用时,它不会返回错误,而是返回不同的状态码,详见:[SHOW CLUSTER ALIVE](https://docs.taosdata.com/reference/taos-sql/show/#show-cluster-alive) ### CURRENT_USER @@ -2300,15 +2298,15 @@ ST_GeomFromText(VARCHAR WKT expr) **功能说明**:根据 Well-Known Text (WKT) 表示从指定的几何值创建几何数据。 -**返回值类型**:GEOMETRY +**返回值类型**:GEOMETRY。 -**适用数据类型**:VARCHAR +**适用数据类型**:VARCHAR。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:输入可以是 WKT 字符串之一,例如点(POINT)、线串(LINESTRING)、多边形(POLYGON)、多点集(MULTIPOINT)、多线串(MULTILINESTRING)、多多边形(MULTIPOLYGON)、几何集合(GEOMETRYCOLLECTION)。输出是以二进制字符串形式定义的 GEOMETRY 数据类型。 -### Geometry 输出函数: +### Geometry 输出函数 #### ST_AsText @@ -2318,15 +2316,15 @@ ST_AsText(GEOMETRY geom) **功能说明**:从几何数据中返回指定的 Well-Known Text (WKT) 表示。 -**返回值类型**:VARCHAR +**返回值类型**:VARCHAR。 -**适用数据类型**:GEOMETRY +**适用数据类型**:GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:输出可以是 WKT 字符串之一,例如点(POINT)、线串(LINESTRING)、多边形(POLYGON)、多点集(MULTIPOINT)、多线串(MULTILINESTRING)、多多边形(MULTIPOLYGON)、几何集合(GEOMETRYCOLLECTION)。 -### Geometry 关系函数: +### Geometry 关系函数 #### ST_Intersects @@ -2336,11 +2334,11 @@ ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) ##功能说明**:比较两个几何对象,并在它们相交时返回 true。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY、GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:如果两个几何对象有任何一个共享点,则它们相交。 @@ -2350,13 +2348,13 @@ ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) ST_Equals(GEOMETRY geomA, GEOMETRY geomB) ``` -**功能说明**:如果给定的几何对象是"空间相等"的,则返回 TRUE。 +**功能说明**:如果给定的几何对象是“空间相等”的,则返回 TRUE。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY、GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:"空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true,并且点的顺序可能不同,但表示相同的几何结构。 @@ -2368,11 +2366,11 @@ ST_Touches(GEOMETRY geomA, GEOMETRY geomB) **功能说明**:如果 A 和 B 相交,但它们的内部不相交,则返回 TRUE。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY、GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:A 和 B 至少有一个公共点,并且这些公共点位于至少一个边界中。对于点/点输入,关系始终为 FALSE,因为点没有边界。 @@ -2384,11 +2382,11 @@ ST_Covers(GEOMETRY geomA, GEOMETRY geomB) **功能说明**:如果 B 中的每个点都位于几何形状 A 内部(与内部或边界相交),则返回 TRUE。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY、GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:A 包含 B 意味着 B 中的没有点位于 A 的外部(在外部)。 @@ -2400,11 +2398,11 @@ ST_Contains(GEOMETRY geomA, GEOMETRY geomB) **功能说明**:如果 A 包含 B,描述:如果几何形状 A 包含几何形状 B,则返回 TRUE。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY,GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:A 包含 B 当且仅当 B 的所有点位于 A 的内部(即位于内部或边界上)(或等效地,B 的没有点位于 A 的外部),并且 A 和 B 的内部至少有一个公共点。 @@ -2416,10 +2414,10 @@ ST_ContainsProperly(GEOMETRY geomA, GEOMETRY geomB) **功能说明**:如果 B 的每个点都位于 A 内部,则返回 TRUE。 -**返回值类型**:BOOL +**返回值类型**:BOOL。 -**适用数据类型**:GEOMETRY,GEOMETRY +**适用数据类型**:GEOMETRY、GEOMETRY。 -**适用表类型**:标准表和超表 +**适用表类型**:表和超级表。 **使用说明**:B 的没有点位于 A 的边界或外部。