From 29d9e9acfcf8a0eb88e48e998f57e0d2d59c15e4 Mon Sep 17 00:00:00 2001
From: Jing Sima <simondominic9997@outlook.com>
Date: Wed, 11 Sep 2024 08:05:54 +0800
Subject: [PATCH] docs:[TS-4893] Add doc for new function.

---
 .../14-reference/03-taos-sql/10-function.md   | 898 +++++++++++++++++-
 1 file changed, 873 insertions(+), 25 deletions(-)

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 ee71abbdec..007e1dd64a 100644
--- a/docs/zh/14-reference/03-taos-sql/10-function.md
+++ b/docs/zh/14-reference/03-taos-sql/10-function.md
@@ -169,14 +169,43 @@ POW(expr1, expr2)
 
 
 #### ROUND
-
 ```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
 
@@ -232,6 +261,297 @@ TAN(expr)
 
 **使用说明**：只能与普通列，选择（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
 
 ```sql
@@ -353,23 +694,150 @@ RTRIM(expr)
 
 **适用于**: 表和超级表。
 
-
-#### SUBSTR
-
+#### TRIM
 ```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
 
@@ -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])
 ```
 
-**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 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
 
@@ -695,6 +1355,148 @@ TODAY()
                 b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。
 - 返回的时间戳精度与当前 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
-STDDEV(expr)
+STDDEV/STDDEV_POP(expr)
 ```
 
-**功能说明**：统计表中某列的均方差。
+**功能说明**：统计表中某列的总体标准差。
 
 **返回数据类型**：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
 
 ```sql
@@ -1045,10 +1891,11 @@ MAX(expr)
 
 **返回数据类型**：同应用的字段。
 
-**适用数据类型**：数值类型。
+**适用数据类型**：数值类型, VARCHAR，NCHAR。
 
 **适用于**：表和超级表。
 
+**使用说明**：max 函数可以接受字符串作为输入参数，当输入参数为字符串类型时，返回最大的字符串值。
 
 ### MIN
 
@@ -1060,10 +1907,11 @@ MIN(expr)
 
 **返回数据类型**：同应用的字段。
 
-**适用数据类型**：数值类型。
+**适用数据类型**：数值类型, VARCHAR，NCHAR。
 
 **适用于**：表和超级表。
 
+**使用说明**：min 函数可以接受字符串作为输入参数，当输入参数为字符串类型时，返回最大的字符串值。
 
 ### MODE