diff --git a/docs/en/05-basic/03-query.md b/docs/en/05-basic/03-query.md index 463f58fd6e..d0aef17f4d 100644 --- a/docs/en/05-basic/03-query.md +++ b/docs/en/05-basic/03-query.md @@ -145,20 +145,19 @@ Query OK, 10 row(s) in set (2.415961s) In TDengine, you can use the window clause to perform aggregation queries by time window partitioning, which is particularly suitable for scenarios requiring analysis of large amounts of time-series data, such as smart meters collecting data every 10s but needing to query the average temperature every 1min. -The window clause allows you to partition the queried data set by windows and aggregate the data within each window, including: - -- Time window (time window) -- State window (status window) -- Session window (session window) -- Event window (event window) - -The logic of window partitioning is shown in the following image: +The window clause allows you to partition the queried data set by windows and aggregate the data within each window. The logic of window partitioning is shown in the following image:
Windowing description
Figure 1. Windowing logic
+- Time Window: Data is divided based on time intervals, supporting sliding and tumbling time windows, suitable for data aggregation over fixed time periods. +- Status Window: Windows are divided based on changes in device status values, with data of the same status value grouped into one window, which closes when the status value changes. +- Session Window: Sessions are divided based on the differences in record timestamps, with records having a timestamp interval less than the predefined value belonging to the same session. +- Event Window: Windows are dynamically divided based on the start and end conditions of events, opening when the start condition is met and closing when the end condition is met. +- Count Window: Windows are divided based on the number of data rows, with each window consisting of a specified number of rows for aggregation calculations. + The syntax for the window clause is as follows: ```sql diff --git a/docs/en/assets/data-querying-01.png b/docs/en/assets/data-querying-01.png index 381d6ec88e..36cc854fe2 100644 Binary files a/docs/en/assets/data-querying-01.png and b/docs/en/assets/data-querying-01.png differ diff --git a/docs/en/assets/data-querying-03.png b/docs/en/assets/data-querying-03.png index 416a14a0a9..b1f4024322 100644 Binary files a/docs/en/assets/data-querying-03.png and b/docs/en/assets/data-querying-03.png differ diff --git a/docs/en/assets/data-querying-04.png b/docs/en/assets/data-querying-04.png index fc83f00193..a249dac3c3 100644 Binary files a/docs/en/assets/data-querying-04.png and b/docs/en/assets/data-querying-04.png differ diff --git a/docs/zh/05-basic/03-query.md b/docs/zh/05-basic/03-query.md index 3f5f25af34..52b825c47c 100644 --- a/docs/zh/05-basic/03-query.md +++ b/docs/zh/05-basic/03-query.md @@ -140,17 +140,16 @@ Query OK, 10 row(s) in set (2.415961s) 在 TDengine 中，你可以使用窗口子句来实现按时间窗口切分方式进行聚合结果查询，这种查询方式特别适用于需要对大量时间序列数据进行分析的场景，例如智能电表每 10s 采集一次数据，但需要查询每隔 1min 的温度平均值。 -窗口子句允许你针对查询的数据集合按照窗口进行切分，并对每个窗口内的数据进行聚合，包含： -- 时间窗口（time window） -- 状态窗口（status window） -- 会话窗口（session window） -- 事件窗口（event window） -- 计数窗口（count window） - -窗口划分逻辑如下图所示： +窗口子句允许你针对查询的数据集合按照窗口进行切分，并对每个窗口内的数据进行聚合。窗口划分逻辑如下图所示。 常用窗口划分逻辑 +- 时间窗口（time window）：根据时间间隔划分数据，支持滑动时间窗口和翻转时间窗口，适用于按固定时间周期进行数据聚合。 +- 状态窗口（status window）：基于设备状态值的变化划分窗口，相同状态值的数据归为一个窗口，状态值改变时窗口关闭。 +- 会话窗口（session window）：根据记录的时间戳差异划分会话，时间戳间隔小于预设值的记录属于同一会话。 +- 事件窗口（event window）：基于事件的开始条件和结束条件动态划分窗口，满足开始条件时窗口开启，满足结束条件时窗口关闭。 +- 计数窗口（count window）：根据数据行数划分窗口，每达到指定行数即为一个窗口，并进行聚合计算。 + 窗口子句语法如下： ```sql 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 9c8e2ebb20..ca7fb18b9f 100644 --- a/docs/zh/14-reference/03-taos-sql/10-function.md +++ b/docs/zh/14-reference/03-taos-sql/10-function.md @@ -65,7 +65,6 @@ ASIN(expr) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - #### ATAN ```sql @@ -84,7 +83,6 @@ ATAN(expr) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - #### CEIL ```sql @@ -121,6 +119,66 @@ COS(expr) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +#### DEGREES + +```sql +DEGREES(expr) +``` + +**功能说明**：计算指定参数由弧度值转为角度后的值。 + +**版本**：v3.3.3.0 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `expr` 为 NULL，则返回 NULL。 +- degree = radian * 180 / π。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +**举例**： +```sql +taos> select degrees(PI()); + degrees(pi()) | +============================ + 180.000000000000000 | +``` + +#### EXP + +```sql +EXP(expr) +``` +**功能说明**：返回 e（自然对数的底）的指定乘方后的值。 + +**版本**：v3.3.3.0 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `expr` 为 NULL，返回 NULL。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +**举例**： +```sql +taos> select exp(2); + exp(2) | +============================ + 7.389056098930650 | +``` + #### FLOOR ```sql @@ -130,6 +188,37 @@ FLOOR(expr) **功能说明**：获得指定字段的向下取整数的结果。 其他使用说明参见 CEIL 函数描述。 +#### LN + +```sql +LN(expr) +``` + +**功能说明**：返回指定参数的自然对数。 + +**版本**：v3.3.3.0 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `expr` 为 NULL，返回 NULL。 +- 如果 `epxr` 小于等于 0，返回 NULL。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +**举例**： +```sql +taos> select ln(10); + ln(10) | +============================ + 2.302585092994046 | +``` + #### LOG ```sql @@ -148,6 +237,71 @@ LOG(expr1[, expr2]) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +#### MOD + +```sql +MOD(expr1, expr2) +``` + +**功能说明**：计算 expr1 % expr2 的结果。 + +**版本**：v3.3.3.0 + +**返回结果类型**：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 | +``` + +#### PI + +```sql +PI() +``` + +**功能说明**：返回圆周率 π 的值。 + +**版本**：v3.3.3.0 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：无。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- π ≈ 3.141592653589793。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +**举例**： +```sql +taos> select pi(); + pi() | +============================ + 3.141592653589793 | +``` #### POW @@ -167,8 +321,85 @@ POW(expr1, expr2) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +#### RADIANS + +```sql +RADIANS(expr) +``` + +**功能说明**：计算指定参数由角度值转为弧度后的值。 + +**版本**：v3.3.3.0 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `expr` 为 NULL，则返回 NULL。 +- radian = degree * π / 180。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +**举例**： +```sql +taos> select radians(180); + radians(180) | +============================ + 3.141592653589793 | +``` + +#### RAND + +```sql +RAND([seed]) +``` + +**功能说明**：返回一个从0到1均匀分布的随机数。 + +**版本**：v3.3.3.0 + +**返回结果类型**：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 | +``` #### ROUND + ```sql ROUND(expr[, digits]) ``` @@ -208,6 +439,49 @@ taos> select round(8888.88,-1); 8890.000000000000000 | ``` +#### SIGN + +```sql +SIGN(expr) +``` + +**功能说明**：返回指定参数的符号。 + +**版本**：v3.3.3.0 + +**返回结果类型**：与指定字段的原始数据类型一致。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `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 | +``` + #### SIN ```sql @@ -262,36 +536,8 @@ TAN(expr) **使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -#### PI -```sql -PI() -``` - -**功能说明**：返回圆周率 π 的值。 - -**版本**：v3.3.3.0 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：无。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- π ≈ 3.141592653589793。 -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -**举例**： -```sql -taos> select pi(); - pi() | -============================ - 3.141592653589793 | -``` - ##### TRUNCATE + ```sql TRUNCATE(expr, digits) ``` @@ -332,249 +578,88 @@ taos> select truncate(8888.88, -1); 8880.000000000000000 | ``` -#### EXP -```sql -EXP(expr) -``` -**功能说明**：返回 e（自然对数的底）的指定乘方后的值。 - -**版本**：v3.3.3.0 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 如果 `expr` 为 NULL，返回 NULL。 -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -**举例**： -```sql -taos> select exp(2); - exp(2) | -============================ - 7.389056098930650 | -``` - -#### LN -```sql -LN(expr) -``` - -**功能说明**：返回指定参数的自然对数。 - -**版本**：v3.3.3.0 - -**返回结果类型**：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 的结果。 - -**版本**：v3.3.3.0 - -**返回结果类型**：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均匀分布的随机数。 - -**版本**：v3.3.3.0 - -**返回结果类型**：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) -``` - -**功能说明**：返回指定参数的符号。 - -**版本**：v3.3.3.0 - -**返回结果类型**：与指定字段的原始数据类型一致。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 如果 `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) -``` - -**功能说明**：计算指定参数由弧度值转为角度后的值。 - -**版本**：v3.3.3.0 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 如果 `expr` 为 NULL，则返回 NULL。 -- degree = radian * 180 / π。 -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -**举例**： -```sql -taos> select degrees(PI()); - degrees(pi()) | -============================ - 180.000000000000000 | -``` - -#### RADIANS -```sql -RADIANS(expr) -``` - -**功能说明**：计算指定参数由角度值转为弧度后的值。 - -**版本**：v3.3.3.0 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 如果 `expr` 为 NULL，则返回 NULL。 -- radian = degree * π / 180。 -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -**举例**： -```sql -taos> select radians(180); - radians(180) | -============================ - 3.141592653589793 | -``` ### 字符串函数 字符串函数的输入参数为字符串类型，返回结果为数值类型或字符串类型。 +#### ASCII + +```sql +ASCII(expr) +``` + +**功能说明**：返回字符串第一个字符的 ASCII 码。 + +**版本**：v3.3.3.0 + +**返回结果数据类型**：BIGINT。 + +**适用数据类型**：VARCHAR、NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 如果 `expr` 为 NULL，返回 NULL。 +- 如果 `expr` 的第一个字符为多字节字符，只会返回该字符第一个字节的值对应的 ASCII 码。 + +**举例**： +```sql +taos> select ascii('testascii'); + ascii('testascii') | +===================== + 116 | +``` + +#### CHAR + +```sql +CHAR(expr1 [, expr2] [, epxr3] ...) +``` + +**功能说明**：将输入参数当作整数，并返回这些整数在 ASCII 编码中对应的字符。 + +**版本**：v3.3.3.0 + +**返回结果类型**：VARCHAR。 + +**适用数据类型**：整数类型,VARCHAR、NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 输入的值超过 255 会被转化成多字节的结果，如 `CHAR(256)` 等同于 `CHAR(1,0)`、`CHAR(256 * 256)` 等同于 `CHAR(1,0,0)`。 +- 输入参数的 NULL 值会被跳过。 +- 输入参数若为字符串类型，会将其转换为数值类型处理。 +- 若输入的参数对应的字符为不可打印字符，返回值中仍有该参数对应的字符，但是可能无法显示出来。 +- 输入参数的个数上限为 2^31 - 1 个。 + +**举例**： +```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 | +``` + #### CHAR_LENGTH ```sql @@ -628,7 +713,6 @@ CONCAT(expr1, expr2 [, expr] ... ) **适用于**：表和超级表。 - #### CONCAT_WS ```sql @@ -645,7 +729,6 @@ CONCAT_WS(separator_expr, expr1, expr2 [, expr] ...) **适用于**：表和超级表。 - #### LENGTH ```sql @@ -662,7 +745,6 @@ LENGTH(expr) **适用于**：表和超级表。 - #### LOWER ```sql @@ -696,6 +778,120 @@ LTRIM(expr) **适用于**：表和超级表。 +#### POSITION + +```sql +POSITION(expr1 IN expr2) +``` + +**功能说明**：计算字符串 `expr1` 在字符串 `expr2` 中的位置。 + +**版本**：v3.3.3.0 + +**返回结果类型**：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 | +``` + +#### REPEAT + +```sql +REPEAT(expr, count) +``` +**功能说明**：返回将字符串重复指定次数得到的字符串。 + +**版本**：v3.3.3.0 + +**返回结果类型**：与输入字段 `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) | +=================== + | +``` + +#### REPLACE + +```sql +REPLACE(expr, from_str, to_str) +``` +**功能说明**：将字符串中的 `from_str` 全部替换为 `to_str`。 + +**版本**：v3.3.3.0 + +**返回结果类型**：与输入字段 `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 | +``` #### RTRIM @@ -713,62 +909,8 @@ RTRIM(expr) **适用于**：表和超级表。 -#### TRIM -```sql -TRIM([{LEADING | TRAILING | BOTH} [remstr] FROM] expr) -TRIM([remstr FROM] expr) -``` - -**功能说明**：返回去掉了所有 remstr 前缀或后缀的字符串 epxr。 - -**版本**：v3.3.3.0 - -**返回结果类型**：与输入字段 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。 -- 该函数是多字节安全的。 - -**举例**： -```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]) @@ -826,6 +968,7 @@ taos> select substring('tdengine', -3,-3); ``` #### SUBSTRING_INDEX + ```sql SUBSTRING_INDEX(expr, delim, count) ``` @@ -864,6 +1007,62 @@ taos> select substring_index('www.taosdata.com','.',-2); taosdata.com | ``` +#### TRIM + +```sql +TRIM([{LEADING | TRAILING | BOTH} [remstr] FROM] expr) +TRIM([remstr FROM] expr) +``` + +**功能说明**：返回去掉了所有 remstr 前缀或后缀的字符串 epxr。 + +**版本**：v3.3.3.0 + +**返回结果类型**：与输入字段 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。 +- 该函数是多字节安全的。 + +**举例**： +```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 | +``` + #### UPPER ```sql @@ -880,193 +1079,6 @@ UPPER(expr) **适用于**：表和超级表。 -#### CHAR -```sql -CHAR(expr1 [, expr2] [, epxr3] ...) -``` - -**功能说明**：将输入参数当作整数，并返回这些整数在 ASCII 编码中对应的字符。 - -**版本**：v3.3.3.0 - -**返回结果类型**：VARCHAR。 - -**适用数据类型**：整数类型,VARCHAR、NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 输入的值超过 255 会被转化成多字节的结果，如 `CHAR(256)` 等同于 `CHAR(1,0)`、`CHAR(256 * 256)` 等同于 `CHAR(1,0,0)`。 -- 输入参数的 NULL 值会被跳过。 -- 输入参数若为字符串类型，会将其转换为数值类型处理。 -- 若输入的参数对应的字符为不可打印字符，返回值中仍有该参数对应的字符，但是可能无法显示出来。 -- 输入参数的个数上限为 2^31 - 1 个。 - -**举例**： -```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 码。 - -**版本**：v3.3.3.0 - -**返回结果数据类型**：BIGINT。 - -**适用数据类型**：VARCHAR、NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： -- 如果 `expr` 为 NULL，返回 NULL。 -- 如果 `expr` 的第一个字符为多字节字符，只会返回该字符第一个字节的值对应的 ASCII 码。 - -**举例**： -```sql -taos> select ascii('testascii'); - ascii('testascii') | -===================== - 116 | -``` - -#### POSITION -```sql -POSITION(expr1 IN expr2) -``` - -**功能说明**：计算字符串 `expr1` 在字符串 `expr2` 中的位置。 - -**版本**：v3.3.3.0 - -**返回结果类型**：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`。 - -**版本**：v3.3.3.0 - -**返回结果类型**：与输入字段 `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) -``` -**功能说明**：返回将字符串重复指定次数得到的字符串。 - -**版本**：v3.3.3.0 - -**返回结果类型**：与输入字段 `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) | -=================== - | -``` ### 转换函数 转换函数将值从一种数据类型转换为另一种数据类型。 @@ -1095,72 +1107,6 @@ CAST(expr AS type_name) - 转换到数值类型时，数值大于 type_name 可表示的范围时，则会溢出，但不会报错。 - 转换到字符串类型时，如果转换后长度超过 type_name 中指定的长度，则会截断，但不会报错。 -#### TO_ISO8601 - -```sql -TO_ISO8601(expr [, timezone]) -``` - -**功能说明**：将时间戳转换成为 ISO8601 标准的日期时间格式，并附加时区信息。timezone 参数允许用户为输出结果指定附带任意时区信息。如果 timezone 参数省略，输出结果则附带当前客户端的系统时区信息。 - -**返回结果数据类型**：VARCHAR 类型。 - -**适用数据类型**：INTEGER、TIMESTAMP。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： - -- timezone 参数允许输入的时区格式为：[z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如，TO_ISO8601(1, "+00:00")。 -- 输入时间戳的精度由所查询表的精度确定，若未指定表，则精度为毫秒. - - -#### TO_JSON - -```sql -TO_JSON(str_literal) -``` - -**功能说明**：将字符串常量转换为 JSON 类型。 - -**返回结果数据类型**：JSON。 - -**适用数据类型**：JSON 字符串，形如 '\{ "literal" : literal }'。'\{}'表示空值。键必须为字符串字面量，值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal 中不支持转义符。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - - -#### TO_UNIXTIMESTAMP - -```sql -TO_UNIXTIMESTAMP(expr [, return_timestamp]) - -return_timestamp: { - 0 - | 1 -} -``` - -**功能说明**：将日期时间格式的字符串转换成为时间戳。 - -**返回结果数据类型**：BIGINT、TIMESTAMP。 - -**应用字段**：VARCHAR、NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 NULL。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 -- return_timestamp 指定函数返回值是否为时间戳类型，设置为 1 时返回 TIMESTAMP 类型，设置为 0 时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 - #### TO_CHAR ```sql @@ -1222,6 +1168,43 @@ TO_CHAR(ts, format_str_literal) - 推荐在时间格式中带时区信息，如果不带则默认输出的时区为服务端或客户端所配置的时区。 - 输入时间戳的精度由所查询表的精度确定，若未指定表，则精度为毫秒。 +#### TO_ISO8601 + +```sql +TO_ISO8601(expr [, timezone]) +``` + +**功能说明**：将时间戳转换成为 ISO8601 标准的日期时间格式，并附加时区信息。timezone 参数允许用户为输出结果指定附带任意时区信息。如果 timezone 参数省略，输出结果则附带当前客户端的系统时区信息。 + +**返回结果数据类型**：VARCHAR 类型。 + +**适用数据类型**：INTEGER、TIMESTAMP。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： + +- timezone 参数允许输入的时区格式为：[z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如，TO_ISO8601(1, "+00:00")。 +- 输入时间戳的精度由所查询表的精度确定，若未指定表，则精度为毫秒. + +#### TO_JSON + +```sql +TO_JSON(str_literal) +``` + +**功能说明**：将字符串常量转换为 JSON 类型。 + +**返回结果数据类型**：JSON。 + +**适用数据类型**：JSON 字符串，形如 '\{ "literal" : literal }'。'\{}'表示空值。键必须为字符串字面量，值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal 中不支持转义符。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + #### TO_TIMESTAMP ```sql @@ -1252,6 +1235,32 @@ TO_TIMESTAMP(ts_str_literal, format_str_literal) - `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`。 +#### TO_UNIXTIMESTAMP + +```sql +TO_UNIXTIMESTAMP(expr [, return_timestamp]) + +return_timestamp: { + 0 + | 1 +} +``` + +**功能说明**：将日期时间格式的字符串转换成为时间戳。 + +**返回结果数据类型**：BIGINT、TIMESTAMP。 + +**应用字段**：VARCHAR、NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 NULL。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 +- return_timestamp 指定函数返回值是否为时间戳类型，设置为 1 时返回 TIMESTAMP 类型，设置为 0 时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 ### 时间和日期函数 @@ -1259,6 +1268,35 @@ TO_TIMESTAMP(ts_str_literal, format_str_literal) 所有返回当前时间的函数，如 NOW、TODAY 和 TIMEZONE，在一条 SQL 语句中不论出现多少次都只会被计算一次。 +#### DAYOFWEEK +```sql +DAYOFWEEK(expr) +``` +**功能说明**：返回输入日期是周几。 + +**版本**：v3.3.3.0 + +**返回结果类型**：BIGINT。 + +**适用数据类型**：表示时间戳的 BIGINT、TIMESTAMP 类型，或符合 ISO8601/RFC3339 标准的日期时间格式的 VARCHAR、NCHAR 类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： +- 返回值 1 代表周日，2 代表周一 ... 7 代表周六 +- 若 `expr` 为 NULL，返回 NULL。 +- 输入时间戳的精度由所查询表的精度确定，若未指定表，则精度为毫秒。 + +**举例**： +```sql +taos> select dayofweek('2000-01-01'); + dayofweek('2000-01-01') | +========================== + 7 | +``` + #### NOW ```sql @@ -1281,7 +1319,6 @@ NOW() b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - #### TIMEDIFF ```sql @@ -1355,7 +1392,6 @@ use_current_timezone: { - 当将时间值截断到一周（1w）时，timetruncate 的计算是基于 Unix 时间戳（1970年1月1日00:00:00 UTC）进行的。Unix 时间戳始于星期四， 因此所有截断后的日期都是星期四。 - #### TIMEZONE ```sql @@ -1370,7 +1406,6 @@ TIMEZONE() **适用于**：表和超级表。 - #### TODAY ```sql @@ -1392,6 +1427,7 @@ TODAY() - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 #### WEEK + ```sql WEEK(expr [, mode]) ``` @@ -1454,35 +1490,6 @@ taos> select week('2000-01-01',3); 52 | ``` -#### WEEKOFYEAR -```sql -WEEKOFYEAR(expr) -``` -**功能说明**：返回输入日期的周数。 - -**版本**：v3.3.3.0 - -**返回结果类型**：BIGINT。 - -**适用数据类型**：表示时间戳的 BIGINT、TIMESTAMP 类型，或符合 ISO8601/RFC3339 标准的日期时间格式的 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) @@ -1512,11 +1519,12 @@ taos> select weekday('2000-01-01'); 5 | ``` -#### DAYOFWEEK +#### WEEKOFYEAR + ```sql -DAYOFWEEK(expr) +WEEKOFYEAR(expr) ``` -**功能说明**：返回输入日期是周几。 +**功能说明**：返回输入日期的周数。 **版本**：v3.3.3.0 @@ -1529,19 +1537,18 @@ DAYOFWEEK(expr) **适用于**：表和超级表。 **使用说明**： -- 返回值 1 代表周日，2 代表周一 ... 7 代表周六。 +- 等同于`WEEK(expr, 3)`，即在每周第一天是周一，返回值范围为 1 - 53，第一个包含四天及以上的周为第 1 周的条件下判断输入日期的周数。 - 若 `expr` 为 NULL，返回 NULL。 -- 输入时间戳的精度由所查询表的精度确定，若未指定表，则精度为毫秒。 - +- 输入时间戳的精度由所查询表的精度确定，未指定表，则精度为毫秒。 + **举例**： ```sql -taos> select dayofweek('2000-01-01'); - dayofweek('2000-01-01') | -========================== - 7 | +taos> select weekofyear('2000-01-01'); + weekofyear('2000-01-01') | +=========================== + 52 | ``` - ## 聚合函数 聚合函数为查询结果集的每一个分组返回单个结果行。可以由 GROUP BY 或窗口切分子句指定分组，如果没有，则整个查询结果集视为一个分组。 @@ -1586,7 +1593,6 @@ AVG(expr) **适用于**：表和超级表。 - ### COUNT ```sql @@ -1606,7 +1612,6 @@ COUNT({* | expr}) - 可以使用星号 (\*) 来替代具体的字段，使用星号 (\*) 返回全部记录数量。 - 如果统计字段是具体的列，则返回该列中非 NULL 值的记录数量。 - ### ELAPSED ```sql @@ -1632,6 +1637,50 @@ ELAPSED(ts_primary_key [, time_unit]) - 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如 `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 等函数混合使用。 +### HISTOGRAM + +```sql +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。 + +### HYPERLOGLOG + +```sql +HYPERLOGLOG(expr) +``` + +**功能说明**： + - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 + - 在数据量较少的时候该算法不是很准确，可以使用 `select count(data) from (select unique(col) as data from table)` 的方法。 + +**返回结果类型**：INTEGER。 + +**适用数据类型**：任何类型。 + +**适用于**：表和超级表。 ### LEASTSQUARES @@ -1648,6 +1697,26 @@ LEASTSQUARES(expr, start_val, step_val) **适用于**：表。 +### PERCENTILE + +```sql +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`。 + ### SPREAD ```sql @@ -1696,7 +1765,23 @@ taos> select stddev_pop(id) from test_stddev; ============================ 1.414213562373095 | ``` + +### SUM + +```sql +SUM(expr) +``` + +**功能说明**：统计表/超级表中某列的和。 + +**返回数据类型**：DOUBLE、BIGINT。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + ### VAR_POP + ```sql VAR_POP(expr) ``` @@ -1727,88 +1812,6 @@ taos> select var_pop(id) from test_var; ============================ 2.000000000000000 | ``` -### SUM - -```sql -SUM(expr) -``` - -**功能说明**：统计表/超级表中某列的和。 - -**返回数据类型**：DOUBLE、BIGINT。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### HYPERLOGLOG - -```sql -HYPERLOGLOG(expr) -``` - -**功能说明**： - - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 - - 在数据量较少的时候该算法不是很准确，可以使用 `select count(data) from (select unique(col) as data from table)` 的方法。 - -**返回结果类型**：INTEGER。 - -**适用数据类型**：任何类型。 - -**适用于**：表和超级表。 - - -### HISTOGRAM - -```sql -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 - -```sql -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`。 - ## 选择函数 @@ -1912,7 +1915,6 @@ LAST(expr) - 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 - 对于存在复合主键的表的查询，若最大时间戳的数据有多条，则只有对应的复合主键最大的数据被返回。 - ### LAST_ROW ```sql @@ -1981,7 +1983,6 @@ MODE(expr) **适用于**：表和超级表。 - ### SAMPLE ```sql @@ -1998,7 +1999,6 @@ SAMPLE(expr, k) **适用于**：表和超级表。 - ### TAIL ```sql @@ -2015,7 +2015,6 @@ TAIL(expr, k [, offset_rows]) **适用于**：表、超级表。 - ### TOP ```sql @@ -2093,11 +2092,9 @@ CSUM(expr) **适用于**：表和超级表。 **使用说明**： - - 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。 - 只能与聚合（Aggregation）函数一起使用。该函数可以应用在普通表和超级表上。 - ### DERIVATIVE ```sql @@ -2173,7 +2170,6 @@ IRATE(expr) **适用于**：表和超级表。 - ### MAVG ```sql @@ -2195,7 +2191,6 @@ MAVG(expr, k) - 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); - 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用； - ### STATECOUNT ```sql @@ -2221,7 +2216,6 @@ STATECOUNT(expr, oper, val) - 不能和窗口操作一起使用，例如 `interval/state_window/session_window`。 - ### STATEDURATION ```sql @@ -2248,7 +2242,6 @@ STATEDURATION(expr, oper, val, unit) - 不能和窗口操作一起使用，例如 interval、state_window、session_window。 - ### TWA ```sql @@ -2263,18 +2256,8 @@ TWA(expr) **适用于**：表和超级表。 - ## 系统信息函数 -### DATABASE - -```sql -SELECT DATABASE(); -``` - -**说明**：返回当前登录的数据库。如果登录的时候没有指定默认数据库，且没有使用 USE 命令切换数据库，则返回 NULL。 - - ### CLIENT_VERSION ```sql @@ -2283,13 +2266,21 @@ SELECT CLIENT_VERSION(); **说明**：返回客户端版本。 -### SERVER_VERSION +### CURRENT_USER ```sql -SELECT SERVER_VERSION(); +SELECT CURRENT_USER(); ``` -**说明**：返回服务端版本。 +**说明**：获取当前用户。 + +### DATABASE + +```sql +SELECT DATABASE(); +``` + +**说明**：返回当前登录的数据库。如果登录的时候没有指定默认数据库，且没有使用 USE 命令切换数据库，则返回 NULL。 ### SERVER_STATUS @@ -2299,14 +2290,13 @@ SELECT SERVER_STATUS(); **说明**：检测服务端是否所有 dnode 都在线，如果是则返回成功，否则返回无法建立连接的错误。如果想要查询集群的状态，推荐使用 `SHOW CLUSTER ALIVE` 与 `SELECT SERVER_STATUS()` 不同，当集群中的部分节点不可用时，它不会返回错误，而是返回不同的状态码，详见：[SHOW CLUSTER ALIVE](https://docs.taosdata.com/reference/taos-sql/show/#show-cluster-alive) -### CURRENT_USER +### SERVER_VERSION ```sql -SELECT CURRENT_USER(); +SELECT SERVER_VERSION(); ``` -**说明**：获取当前用户。 - +**说明**：返回服务端版本。 ## Geometry 函数 @@ -2348,70 +2338,6 @@ ST_AsText(GEOMETRY geom) ### Geometry 关系函数 -#### ST_Intersects - -```sql -ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) -``` - -##功能说明**：比较两个几何对象，并在它们相交时返回 true。 - -**返回值类型**：BOOL。 - -**适用数据类型**：GEOMETRY、GEOMETRY。 - -**适用表类型**：标准表和超表。 - -**使用说明**：如果两个几何对象有任何一个共享点，则它们相交。 - -#### ST_Equals - -```sql -ST_Equals(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果给定的几何对象是“空间相等”的，则返回 TRUE。 - -**返回值类型**：BOOL。 - -**适用数据类型**：GEOMETRY、GEOMETRY。 - -**适用表类型**：标准表和超表。 - -**使用说明**："空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true，并且点的顺序可能不同，但表示相同的几何结构。 - -#### ST_Touches - -```sql -ST_Touches(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 A 和 B 相交，但它们的内部不相交，则返回 TRUE。 - -**返回值类型**：BOOL。 - -**适用数据类型**：GEOMETRY、GEOMETRY。 - -**适用表类型**：标准表和超表。 - -**使用说明**：A 和 B 至少有一个公共点，并且这些公共点位于至少一个边界中。对于点/点输入，关系始终为 FALSE，因为点没有边界。 - -#### ST_Covers - -```sql -ST_Covers(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 B 中的每个点都位于几何形状 A 内部（与内部或边界相交），则返回 TRUE。 - -**返回值类型**：BOOL。 - -**适用数据类型**：GEOMETRY、GEOMETRY。 - -**适用表类型**：标准表和超表。 - -**使用说明**：A 包含 B 意味着 B 中的没有点位于 A 的外部（在外部）。 - #### ST_Contains ```sql @@ -2443,3 +2369,68 @@ ST_ContainsProperly(GEOMETRY geomA, GEOMETRY geomB) **适用表类型**：标准表和超表。 **使用说明**：B 的没有点位于 A 的边界或外部。 + +#### ST_Covers + +```sql +ST_Covers(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 B 中的每个点都位于几何形状 A 内部（与内部或边界相交），则返回 TRUE。 + +**返回值类型**：BOOL。 + +**适用数据类型**：GEOMETRY、GEOMETRY。 + +**适用表类型**：标准表和超表。 + +**使用说明**：A 包含 B 意味着 B 中的没有点位于 A 的外部（在外部）。 + +#### ST_Equals + +```sql +ST_Equals(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果给定的几何对象是"空间相等"的，则返回 TRUE。 + +**返回值类型**：BOOL。 + +**适用数据类型**：GEOMETRY、GEOMETRY。 + +**适用表类型**：标准表和超表。 + +**使用说明**："空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true，并且点的顺序可能不同，但表示相同的几何结构。 + + +#### ST_Intersects + +```sql +ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) +``` + +##功能说明**：比较两个几何对象，并在它们相交时返回 true。 + +**返回值类型**：BOOL。 + +**适用数据类型**：GEOMETRY、GEOMETRY。 + +**适用表类型**：标准表和超表。 + +**使用说明**：如果两个几何对象有任何一个共享点，则它们相交。 + +#### ST_Touches + +```sql +ST_Touches(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 A 和 B 相交，但它们的内部不相交，则返回 TRUE。 + +**返回值类型**：BOOL。 + +**适用数据类型**：GEOMETRY、GEOMETRY。 + +**适用表类型**：标准表和超表。 + +**使用说明**：A 和 B 至少有一个公共点，并且这些公共点位于至少一个边界中。对于点/点输入，关系始终为 FALSE，因为点没有边界。