xxq250
/
homework-jianmu
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs:[TS-4893] Add doc for new function.

This commit is contained in:
Jing Sima 2024-09-11 08:05:54 +08:00
parent 0f7b2ea467
commit 29d9e9acfc
1 changed files with 873 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

898
docs/zh/14-reference/03-taos-sql/10-function.md
View File

@ -169,14 +169,43 @@ POW(expr1, expr2)
#### ROUND #### ROUND
```sql ```sql
ROUND(expr) ROUND(expr[, digits])
``` ```
**功能说明**：获得指定字段的四舍五入的结果。 **功能说明**：获得指定字段的四舍五入的结果。
其他使用说明参见 CEIL 函数描述。
**返回结果类型**：与指定字段的原始数据类型一致。
**适用数据类型**：
- `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）函数一起使用。
**举例**：
```sql
taos> select round(8888.88);
round(8888.88) |
============================
8889.000000000000000 |
taos> select round(8888.88,-1);
round(8888.88,-1) |
============================
8890.000000000000000 |
```
#### SIN #### SIN
@ -232,6 +261,297 @@ TAN(expr)
**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
#### PI
```sql
PI()
```
**功能说明**：返回圆周率 π 的值。
**返回结果类型**：DOUBLE。
**适用数据类型**：无。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- π ≈ 3.141592653589793。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select pi();
pi() |
============================
3.141592653589793 |
```
##### TRUNCATE
```sql
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）函数一起使用。
**举例**：
```sql
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
```sql
EXP(expr)
```
**功能说明**：返回 e（自然对数的底）的指定乘方后的值。
**返回结果类型**：DOUBLE。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为 NULL，返回 NULL。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select exp(2);
exp(2) |
============================
7.389056098930650 |
```
#### LN
```sql
LN(expr)
```
**功能说明**：返回指定参数的自然对数。
**返回结果类型**：DOUBLE。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为 NULL，返回 NULL。
- 如果 `epxr` 小于等于 0，返回 NULL。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select ln(10);
ln(10) |
============================
2.302585092994046 |
```
#### MOD
```sql
MOD(expr1, expr2)
```
**功能说明**：计算 expr1 % expr2 的结果。
**返回结果类型**：DOUBLE。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr2` 为 0 则返回 NULL。
- 如果 `expr1` 或 `expr2` 为 NULL，返回 NULL。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
``` sql
taos> select mod(10,3);
mod(10,3) |
============================
1.000000000000000 |
taos> select mod(1,0);
mod(1,0) |
============================
NULL |
```
#### RAND
```sql
RAND([seed])
```
**功能说明**：返回一个从0到1均匀分布的随机数。
**返回结果类型**：DOUBLE。
**适用数据类型**：
- `seed`：INTEGER。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果指定了 `seed` 值，那么将会用指定的 `seed` 作为随机种子，确保生成的随机数序列具有确定性。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
``` sql
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
```sql
SIGN(expr)
```
**功能说明**：返回指定参数的符号。
**返回结果类型**：与指定字段的原始数据类型一致。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为负，返回 -1 ，
- 如果 `expr` 为正，返回 1 ，
- 如果 `expr` 为 0 ，返回 0 。
- 如果 `expr` 为 NULL ，返回 NULL 。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select sign(-1);
sign(-1) |
========================
-1 |
taos> select sign(1);
sign(1) |
========================
1 |
taos> select sign(0);
sign(0) |
========================
0 |
```
#### DEGREES
```sql
DEGREES(expr)
```
**功能说明**：计算指定参数由弧度值转为角度后的值。
**返回结果类型**：DOUBLE。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为 NULL，则返回 NULL。
- degree = radian * 180 / π。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select degrees(PI());
degrees(pi()) |
============================
180.000000000000000 |
```
#### RADIANS
```sql
RADIANS(expr)
```
**功能说明**：计算指定参数由角度值转为弧度后的值。
**返回结果类型**：DOUBLE。
**适用数据类型**：数值类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为 NULL，则返回 NULL。
- radian = degree * π / 180。
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。
**举例**：
```sql
taos> select radians(180);
radians(180) |
============================
3.141592653589793 |
```
### 字符串函数 ### 字符串函数
字符串函数的输入参数为字符串类型，返回结果为数值类型或字符串类型。 字符串函数的输入参数为字符串类型，返回结果为数值类型或字符串类型。
@ -252,6 +572,27 @@ CHAR_LENGTH(expr)
**适用于**: 表和超级表。 **适用于**: 表和超级表。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 与 `LENGTH()` 函数不同在于，对于多字节字符，比如中文字符， `CHAR_LENGTH()` 函数会将其算做一个字符，长度为 1，而 `LENGTH()` 会计算其字节数，长度为 3。比如 `CHAR_LENGTH('你好') = 2`， `LENGTH('你好') = 6`。
- 如果 `expr` 为 NULL，返回 NULL。
**举例**：
```sql
taos> select char_length('Hello world');
char_length('Hello world') |
=============================
11 |
taos> select char_length('你好 世界');
char_length('你好 世界') |
===============================
5 |
```
#### CONCAT #### CONCAT
```sql ```sql
@ -353,23 +694,150 @@ RTRIM(expr)
**适用于**: 表和超级表。 **适用于**: 表和超级表。
#### TRIM
#### SUBSTR
```sql ```sql
SUBSTR(expr, pos [,len]) TRIM([{LEADING | TRAILING | BOTH} [remstr] FROM] expr)
TRIM([remstr FROM] expr)
``` ```
**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。如果输入参数 len 被忽略，返回的子串包含从 pos 开始的整个字串。 **功能说明**：返回去掉了所有 remstr 前缀或后缀的字符串 epxr 。
**返回结果类型**：与输入字段的原始类型相同。 **返回结果类型**：与输入字段 epxr 的原始类型相同。
**适用数据类型**：VARCHAR, NCHAR。输入参数 pos 可以为正数，也可以为负数。如果 pos 是正数，表示开始位置从字符串开头正数计算。如果 pos 为负数，表示开始位置从字符串结尾倒数计算。 **适用数据类型**：
- remstr：VARCHAR,NCHAR。
- epxr：VARCHAR,NCHAR。
**嵌套子查询支持**：适用于内层查询和外层查询。 **嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。 **适用于**: 表和超级表。
**使用说明**：
- 第一个可选变量[LEADING | BOTH | TRAILING]指定要剪裁字符串的哪一侧：
- LEADING 将移除字符串开头的指定字符。
- TRAILING 将移除字符串末尾的指定字符。
- BOTH（默认值）将移除字符串开头和末尾的指定字符。
- 第二个可选变量[remstr]指定要裁剪掉的字符串：
- 如果不指定 remstr ，默认裁剪空格。
- remstr 可以指定多个字符，如trim('ab' from 'abacd') ，此时会将 'ab' 看做一个整体来裁剪，得到裁剪结果 'acd'。
- 若 expr 为 NULL, 返回 NULL。
- 该函数是多字节安全的。
**举例**：
```sql
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
```sql
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)`。
**举例**：
```sql
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
```sql
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。
- 该函数是多字节安全的。
**举例**：
```sql
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
@ -387,7 +855,182 @@ UPPER(expr)
**适用于**: 表和超级表。 **适用于**: 表和超级表。
#### CHAR
```sql
CHAR(expr1 [, expr2] [, epxr3] ...)
```
**功能说明**：将输入参数当作整数，并返回这些整数在 ASCII 编码中对应的字符。
**返回结果类型**：VARCHAR。
**适用数据类型**：整数类型,VARCHAR,NCHAR。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 输入的值超过 255 会被转化成多字节的结果，如 `CHAR(256)` 等同于 `CHAR(1,0)`, `CHAR(256 * 256)` 等同于 `CHAR(1,0,0)`。
- 输入参数的 NULL 值会被跳过。
- 输入参数若为字符串类型，会将其转换为数值类型处理。
- 若输入的参数对应的字符为不可打印字符，返回值中仍有该参数对应的字符，但是可能无法显示出来。
**举例**：
```sql
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
```sql
ASCII(expr)
```
**功能说明**：返回字符串第一个字符的 ASCII 码。
**返回结果数据类型**：BIGINT。
**适用数据类型**：VARCHAR, NCHAR。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 如果 `expr` 为 NULL，返回 NULL。
- 如果 `expr` 的第一个字符为多字节字符，只会返回该字符第一个字节的值对应的 ASCII 码。
**举例**：
```sql
taos> select ascii('testascii');
ascii('testascii') |
=====================
116 |
```
#### POSITION
```sql
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 的。
- 该函数是多字节安全的。
**举例**：
```sql
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
```sql
REPLACE(expr, from_str, to_str)
```
**功能说明**：将字符串中的 `from_str` 全部替换为 `to_str`。
**返回结果类型**：与输入字段 `expr` 的原始类型相同。
**适用数据类型**：
- `expr`：VARCHAR, NCHAR。
- `from_str`：VARCHAR, NCHAR。
- `to_str`：VARCHAR, NCHAR。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 该函数是大小写敏感的。
- 任意参数为 NULL，返回 NULL。
- 该函数是多字节安全的。
**举例**：
```sql
taos> select replace('aabbccAABBCC', 'AA', 'DD');
replace('aabbccAABBCC', 'AA', 'DD') |
======================================
aabbccDDBBCC |
```
#### REPEAT
```sql
REPEAT(expr, count)
```
**功能说明**：返回将字符串重复指定次数得到的字符串。
**返回结果类型**：与输入字段 `expr` 的原始类型相同。
**适用数据类型**：
- `expr`： VARCHAR,NCHAR。
- `count`：INTEGER。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 若 `count < 1`，返回空串。
- 若 `expr` 或 `count` 为 NULL，返回 NULL。
**举例**：
```sql
taos> select repeat('abc',5);
repeat('abc',5) |
============================
abcabcabcabcabc |
taos> select repeat('abc',-1);
repeat('abc',-1) |
===================
|
```
### 转换函数 ### 转换函数
转换函数将值从一种数据类型转换为另一种数据类型。 转换函数将值从一种数据类型转换为另一种数据类型。
@ -609,22 +1252,39 @@ NOW()
TIMEDIFF(expr1, expr2 [, time_unit]) TIMEDIFF(expr1, expr2 [, time_unit])
``` ```
**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 **功能说明**：返回时间戳 `expr1` - `expr2` 的结果，结果可能为负，并近似到时间单位 `time_unit` 指定的精度。
**返回结果数据类型**：BIGINT。 **返回结果类型**：BIGINT。
**应用字段**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。 **适用数据类型**：
- `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。
**使用说明**：
- 支持的时间单位 `time_unit` 如下： 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。
- 如果时间单位 `time_unit` 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。
- 输入包含不符合时间日期格式的字符串则返回 NULL。
- `expr1` 或 `expr2` 为 NULL，返回 NULL。
- `time_unit` 为 NULL，等同于未指定时间单位。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
**举例**：
```sql
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
@ -695,6 +1355,148 @@ TODAY()
b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
#### WEEK
```sql
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。
**举例**：
```sql
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
```sql
WEEKOFYEAR(expr)
```
**功能说明**：返回输入日期的周数。
**返回结果类型**：BIGINT。
**适用数据类型**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 等同于`WEEK(expr, 3)`，即在每周第一天是周一，返回值范围为 1 - 53，第一个包含四天及以上的周为第 1 周的条件下判断输入日期的周数。
- 若 `expr` 为 NULL，返回 NULL。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
**举例**：
```sql
taos> select weekofyear('2000-01-01');
weekofyear('2000-01-01') |
===========================
52 |
```
#### WEEKDAY
```sql
WEEKDAY(expr)
```
**功能说明**：返回输入日期是周几。
**返回结果类型**：BIGINT。
**适用数据类型**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 返回值 0 代表周日，1 代表周一 ... 6 代表周六。
- 若 `expr` 为 NULL，返回 NULL。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
**举例**：
```sql
taos> select weekday('2000-01-01');
weekday('2000-01-01') |
========================
5 |
```
#### DAYOFWEEK
```sql
DAYOFWEEK(expr)
```
**功能说明**：返回输入日期是周几。
**返回结果类型**：BIGINT。
**适用数据类型**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。
**嵌套子查询支持**：适用于内层查询和外层查询。
**适用于**: 表和超级表。
**使用说明**：
- 返回值 1 代表周日，2 代表周一 ... 7 代表周六
- 若 `expr` 为 NULL，返回 NULL。
- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒.
**举例**：
```sql
taos> select dayofweek('2000-01-01');
dayofweek('2000-01-01') |
==========================
7 |
```
## 聚合函数 ## 聚合函数
@ -817,13 +1619,13 @@ SPREAD(expr)
**适用于**：表和超级表。 **适用于**：表和超级表。
### STDDEV ### STDDEV/STDDEV_POP
```sql ```sql
STDDEV(expr) STDDEV/STDDEV_POP(expr)
``` ```
**功能说明**：统计表中某列的均方差。 **功能说明**：统计表中某列的总体标准差。
**返回数据类型**：DOUBLE。 **返回数据类型**：DOUBLE。
@ -831,7 +1633,51 @@ STDDEV(expr)
**适用于**：表和超级表。 **适用于**：表和超级表。
**举例**：
```sql
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
```sql
VAR_POP(expr)
```
**功能说明**：统计表中某列的总体方差。
**返回数据类型**：DOUBLE。
**适用数据类型**：数值类型。
**适用于**：表和超级表。
**举例**:
```sql
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
```sql ```sql
@ -1045,10 +1891,11 @@ MAX(expr)
**返回数据类型**：同应用的字段。 **返回数据类型**：同应用的字段。
**适用数据类型**：数值类型。 **适用数据类型**：数值类型, VARCHAR，NCHAR。
**适用于**：表和超级表。 **适用于**：表和超级表。
**使用说明**：max 函数可以接受字符串作为输入参数，当输入参数为字符串类型时，返回最大的字符串值。
### MIN ### MIN
@ -1060,10 +1907,11 @@ MIN(expr)
**返回数据类型**：同应用的字段。 **返回数据类型**：同应用的字段。
**适用数据类型**：数值类型。 **适用数据类型**：数值类型, VARCHAR，NCHAR。
**适用于**：表和超级表。 **适用于**：表和超级表。
**使用说明**：min 函数可以接受字符串作为输入参数，当输入参数为字符串类型时，返回最大的字符串值。
### MODE ### MODE