From 0a0de45f928cdc64a84d08e91feae0f63dbb0d62 Mon Sep 17 00:00:00 2001 From: facetosea <25808407@qq.com> Date: Wed, 10 Jul 2024 09:15:10 +0800 Subject: [PATCH 1/4] diff desc online --- docs/en/12-taos-sql/10-function.md | 29 +++++++++++++++++++++-------- docs/zh/12-taos-sql/10-function.md | 29 +++++++++++++++++++++-------- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md index afcebcb818..b1c6f6c129 100644 --- a/docs/en/12-taos-sql/10-function.md +++ b/docs/en/12-taos-sql/10-function.md @@ -1209,27 +1209,40 @@ ignore_negative: { ### DIFF ```sql -DIFF(expr [, ignore_negative]) +DIFF(expr [, ignore_option]) -ignore_negative: { +ignore_option: { 0 | 1 + | 2 + | 3 } ``` -**Description**: The different of each row with its previous row for a specific column. `ignore_negative` can be specified as 0 or 1, the default value is 1 if it's not specified. `1` means negative values are ignored. For tables with composite primary key, the data with the smallest primary key value is used to calculate the difference. +**Description**: The different of each row with its previous row for a specific column. `ignore_option` takes the value of 0|1|2|3, the default value is 0 if it's not specified. +- `0` means that negative values ​​(diff results) are not ignored and null values ​​are not ignored +- `1` means that negative values ​​(diff results) are treated as null values +- `2` means that negative values ​​(diff results) are not ignored but null values ​​are ignored +- `3` means that negative values ​​(diff results) are ignored and null values ​​are ignored +- For tables with composite primary key, the data with the smallest primary key value is used to calculate the difference. -**Return value type**:Same as the data type of the column being operated upon +**Return value type**: `bool`, `timestamp` type and integer value type all return `int_64`, `floating` point type returns `double`, and if the diff result overflows, it is returned as overflow. -**Applicable data types**: Numeric +**Applicable data types**: Numeric type, timestamp and bool type. **Applicable table types**: standard tables and supertables **More explanation**: -- The number of result rows is the number of rows subtracted by one, no output for the first row -- It can be used together with a selected column. For example: select \_rowts, DIFF() from. - +- diff is to diff the data in current row and column with the **first valid data before**. The **first valid data before** refers to sorting by timestamp, searching current this row to the direction of smaller timestamps, checking the same column of other rows, and finding the first non-null data. +- The diff result of numeric type is the corresponding difference; the timestamp is calculated based on the timestamp of the precision type of the database creation; the difference is calculated for bool type true as 1 and false as 0 +- When the row and column data does not exist (null), or no valid comparison data is found, the diff result is null +- When ignoring negative values ​​(ignore_option is 1/3), if the diff result is negative, the result is set to null, and then filtered according to the null value filtering rule +- When the diff result has a type overflow, the positive and negative results of the logical operation are used to determine whether to ignore the negative value. For example, the value of 9223372036854775800 - (-9223372036854775806) exceeds the range of BIGINT, and the diff result will display the overflow value -10, but it will not be ignored as a negative value +- Supports single or multiple diffs in a single statement, and supports different diff functions to specify the same or different ignore_option , when there are multiple diffs, only when all diff results of a row are null and ignore_option is set to ignore null values, the row will be removed from the result set +- Can be used with the selected associated columns. For example: select _rowts, DIFF() from. +- When not using a composite primary key, the sub-tables of the super table may have the same timestamp data. If there are the same timestamps, it will prompt "Duplicate timestamps not allowed" +- When using a composite primary key, the sub-tables of the super table may have the same composite primary key, whichever row is found first will prevail ### IRATE diff --git a/docs/zh/12-taos-sql/10-function.md b/docs/zh/12-taos-sql/10-function.md index 3e78ac0da0..ef63669458 100644 --- a/docs/zh/12-taos-sql/10-function.md +++ b/docs/zh/12-taos-sql/10-function.md @@ -1200,27 +1200,40 @@ ignore_negative: { ### DIFF ```sql -DIFF(expr [, ignore_negative]) +DIFF(expr [, ignore_option]) -ignore_negative: { +ignore_option: { 0 | 1 + | 2 + | 3 } ``` -**功能说明**：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。对于你存在复合主键的表的查询，若时间戳相同的数据存在多条，则只有对应的复合主键最小的数据参与运算。 +**功能说明**：统计表中某列的值与之前行有效值的差。 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 类型。 **适用于**：表和超级表。 **使用说明**: -- 输出结果行数是范围内总行数减一，第一行没有结果输出。 -- 可以与选择相关联的列一起使用。 例如: select \_rowts, DIFF() from。 - +- diff 是本行本列数据和之前最近的第一个有效数据做 diff，之前最近的第一个有效数据：指的是按照时间戳排序，从本行向较小的时间戳方向寻找，查看其他行的同一列，寻找到的第一个非 null 数据。 +- 数值类型 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" +- 使用复合主键时，超级表的子表可能有相同的复合主键，以首先找到的行数据为准 ### IRATE From 3e4822b8dd91780d5360968cd70990f8e6005931 Mon Sep 17 00:00:00 2001 From: wade zhang <95411902+gccgdb1234@users.noreply.github.com> Date: Wed, 10 Jul 2024 11:01:50 +0800 Subject: [PATCH 2/4] Update 10-function.md --- docs/en/12-taos-sql/10-function.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md index b1c6f6c129..93e04f3255 100644 --- a/docs/en/12-taos-sql/10-function.md +++ b/docs/en/12-taos-sql/10-function.md @@ -1219,7 +1219,7 @@ ignore_option: { } ``` -**Description**: The different of each row with its previous row for a specific column. `ignore_option` takes the value of 0|1|2|3, the default value is 0 if it's not specified. +**Description**: The difference of each row with its previous row for a specific column. `ignore_option` takes the value of 0|1|2|3, the default value is 0 if it's not specified. - `0` means that negative values ​​(diff results) are not ignored and null values ​​are not ignored - `1` means that negative values ​​(diff results) are treated as null values - `2` means that negative values ​​(diff results) are not ignored but null values ​​are ignored @@ -1234,15 +1234,15 @@ ignore_option: { **More explanation**: -- diff is to diff the data in current row and column with the **first valid data before**. The **first valid data before** refers to sorting by timestamp, searching current this row to the direction of smaller timestamps, checking the same column of other rows, and finding the first non-null data. -- The diff result of numeric type is the corresponding difference; the timestamp is calculated based on the timestamp of the precision type of the database creation; the difference is calculated for bool type true as 1 and false as 0 -- When the row and column data does not exist (null), or no valid comparison data is found, the diff result is null -- When ignoring negative values ​​(ignore_option is 1/3), if the diff result is negative, the result is set to null, and then filtered according to the null value filtering rule -- When the diff result has a type overflow, the positive and negative results of the logical operation are used to determine whether to ignore the negative value. For example, the value of 9223372036854775800 - (-9223372036854775806) exceeds the range of BIGINT, and the diff result will display the overflow value -10, but it will not be ignored as a negative value -- Supports single or multiple diffs in a single statement, and supports different diff functions to specify the same or different ignore_option , when there are multiple diffs, only when all diff results of a row are null and ignore_option is set to ignore null values, the row will be removed from the result set -- Can be used with the selected associated columns. For example: select _rowts, DIFF() from. -- When not using a composite primary key, the sub-tables of the super table may have the same timestamp data. If there are the same timestamps, it will prompt "Duplicate timestamps not allowed" -- When using a composite primary key, the sub-tables of the super table may have the same composite primary key, whichever row is found first will prevail +- diff is to calculate the difference of a specific column in current row and the **first valid data before the row**. The **first valid data before the row** refers to the most adjacent non-null value of same column with smaller timestamp. +- The diff result of numeric type is the corresponding arithmatic difference; the timestamp is calculated based on the timestamp precision of the database; when calculating diff, `true` is treated as 1 and `false` is treated as 0 +- If the data of current row is NULL or can't find the **first valid data before the current row**, the diff result is NULL +- When ignoring negative values ​​(ignore_option is set to 1 or 3), if the diff result is negative, the result is set to null, and then filtered according to the null value filtering rule +- When the diff result has an overflow, whether to ignore the negative value depends on the result of the logical operation is positive or negative. For example, the value of 9223372036854775800 - (-9223372036854775806) exceeds the range of BIGINT, and the diff result will display the overflow value -10, but it will not be ignored as a negative value +- Single or multiple diffs can be used in a single statement, and for each diff you can specify same or different `ignore_option`. When there are multiple diffs in a single statement, when and only when all the diff results are NULL for a row and the `ignore_option` is specified as ignoring NULL for all diffs, the output of this row will be removed from the result set. +- Can be used with the selected associated columns. For example: `select _rowts, DIFF()`. +- When there is not composite primary key, if there are the same timestamps across different subtables, it will prompt "Duplicate timestamps not allowed" +- When using with composite primary key, there may be same combination of timestamp and complete primary key across sub-tables, which row will be used depends on which row is found first, that means the result of running diff() multiple times may be different in such a case ### IRATE From fe0737e5bf54e89add8e3e2ff49494c0147fced0 Mon Sep 17 00:00:00 2001 From: wade zhang <95411902+gccgdb1234@users.noreply.github.com> Date: Wed, 10 Jul 2024 11:23:49 +0800 Subject: [PATCH 3/4] Update 10-function.md --- docs/en/12-taos-sql/10-function.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md index 93e04f3255..29cf4f74e5 100644 --- a/docs/en/12-taos-sql/10-function.md +++ b/docs/en/12-taos-sql/10-function.md @@ -1226,7 +1226,7 @@ ignore_option: { - `3` means that negative values ​​(diff results) are ignored and null values ​​are ignored - For tables with composite primary key, the data with the smallest primary key value is used to calculate the difference. -**Return value type**: `bool`, `timestamp` type and integer value type all return `int_64`, `floating` point type returns `double`, and if the diff result overflows, it is returned as overflow. +**Return value type**: `bool`, `timestamp` and `integer` value type all return `int_64`, `float` type returns `double`; if the diff result overflows, it is returned as overflow. **Applicable data types**: Numeric type, timestamp and bool type. From 706013e2cd22e840b0256483dd02b2c94cd9d576 Mon Sep 17 00:00:00 2001 From: facetosea <25808407@qq.com> Date: Wed, 10 Jul 2024 15:18:19 +0800 Subject: [PATCH 4/4] Update 10-function.md --- docs/en/12-taos-sql/10-function.md | 2 +- docs/zh/12-taos-sql/10-function.md | 30 +++++++++++++++--------------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md index 29cf4f74e5..e130442279 100644 --- a/docs/en/12-taos-sql/10-function.md +++ b/docs/en/12-taos-sql/10-function.md @@ -1239,7 +1239,7 @@ ignore_option: { - If the data of current row is NULL or can't find the **first valid data before the current row**, the diff result is NULL - When ignoring negative values ​​(ignore_option is set to 1 or 3), if the diff result is negative, the result is set to null, and then filtered according to the null value filtering rule - When the diff result has an overflow, whether to ignore the negative value depends on the result of the logical operation is positive or negative. For example, the value of 9223372036854775800 - (-9223372036854775806) exceeds the range of BIGINT, and the diff result will display the overflow value -10, but it will not be ignored as a negative value -- Single or multiple diffs can be used in a single statement, and for each diff you can specify same or different `ignore_option`. When there are multiple diffs in a single statement, when and only when all the diff results are NULL for a row and the `ignore_option` is specified as ignoring NULL for all diffs, the output of this row will be removed from the result set. +- Single or multiple diffs can be used in a single statement, and for each diff you can specify same or different `ignore_option`. When there are multiple diffs in a single statement, when and only when all the diff results are NULL for a row and each diff's `ignore_option` is specified as ignoring NULL, the output of this row will be removed from the result set. - Can be used with the selected associated columns. For example: `select _rowts, DIFF()`. - When there is not composite primary key, if there are the same timestamps across different subtables, it will prompt "Duplicate timestamps not allowed" - When using with composite primary key, there may be same combination of timestamp and complete primary key across sub-tables, which row will be used depends on which row is found first, that means the result of running diff() multiple times may be different in such a case diff --git a/docs/zh/12-taos-sql/10-function.md b/docs/zh/12-taos-sql/10-function.md index ef63669458..ca6ba378ca 100644 --- a/docs/zh/12-taos-sql/10-function.md +++ b/docs/zh/12-taos-sql/10-function.md @@ -1210,14 +1210,14 @@ 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、时间戳及整型数值类型均返回 int_64，浮点类型返回 double, 若 diff 结果溢出则返回溢出后的值。 **适用数据类型**：数值类型、时间戳和 bool 类型。 @@ -1225,15 +1225,15 @@ ignore_option: { **使用说明**: -- diff 是本行本列数据和之前最近的第一个有效数据做 diff，之前最近的第一个有效数据：指的是按照时间戳排序，从本行向较小的时间戳方向寻找，查看其他行的同一列，寻找到的第一个非 null 数据。 -- 数值类型 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 是计算本行特定列与同列的前一个有效数据的差值，同列的前一个有效数据：指的是同一列中时间戳较小的最临近的非空值。 +- 数值类型 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