amorynan commented on code in PR #2671: URL: https://github.com/apache/doris-website/pull/2671#discussion_r2244269461
########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-difference.md: ########## @@ -5,57 +5,183 @@ } --- +## array_difference + +<version since="2.0.0"> + +</version> + ## 描述 -计算相邻数组元素之间的差异。返回一个数组，其中第一个元素将为 0，第二个元素是 a[1]-a[0]之间的差值。 -注意若 NULL 值存在，返回结果为 NULL + +计算数组中相邻元素的差值。函数会从左到右遍历数组，计算每个元素与其前一个元素的差值，返回一个与原数组等长的新数组。第一个元素的差值始终为 0。 ## 语法 + ```sql -ARRAY_DIFFERENCE(<arr>) +array_difference(ARRAY<T> arr) ``` -## 参数 -| 参数 | 说明 | -|---|---| -| `<arr>` | 用于相邻数组元素之间的差异的数组 | +### 参数 + +- `arr`：ARRAY\<T> 类型，要计算差值的数组。支持列名或常量值。 + +**T 支持的类型：** +- 整数类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT +- 浮点数类型：FLOAT、DOUBLE +- 十进制类型：DECIMALV2、DECIMALV3（包括DECIMAL32、DECIMAL64、DECIMAL128I、DECIMAL256） -## 返回值 -返回一个数组。特殊情况： -- 如果 NULL 值存在，返回结果为 NULL -## 举例 +### 返回值 + +返回类型：ARRAY\<T> + +返回值含义： +- 返回一个与输入数组等长的新数组，每个位置的值为当前元素与前一个元素的差值，第一个元素的差值为 0 +- NULL：如果输入数组为 NULL + +使用说明： +- 函数会尝试将所有元素转换为兼容的数值类型进行差值计算。仅支持以下类型的直接计算： + - 整数类型（TINYINT、SMALLINT、INT、BIGINT、LARGEINT） + - 浮点类型（FLOAT、DOUBLE） + - 十进制类型（DECIMALV2、DECIMALV3，包括 DECIMAL32、DECIMAL64、DECIMAL128I、DECIMAL256） +- 如果数组包含其他类型（如字符串、日期等），会尝试将元素转换为 DOUBLE 类型。转换失败的元素结果为 null，不参与差值计算。 +- 差值的返回类型根据输入类型自动选择： + - 输入为 DOUBLE 或 FLOAT 时，返回 ARRAY\<DOUBLE> + - 输入为整数类型时，返回 ARRAY\<BIGINT> 或 ARRAY\<LARGEINT> + - 输入为 DECIMAL 时，返回 ARRAY\<DECIMAL>，保持原精度和标度 +- 差值的计算顺序为从左到右，每个位置的值为当前元素与前一个元素的差值，第一个元素为 0。 +- 空数组返回空数组，NULL 数组返回 NULL，只有一个元素的数组返回 [0]。 +- 复杂类型（嵌套数组、MAP、STRUCT）不支持差值计算，调用会报错。 +- 函数是 nullsafe 的 +- 对数组元素中的 null 值：null 元素会影响后续差值计算，前一个元素为 null 时，当前差值为 null + +### 示例 ```sql -CREATE TABLE array_type_table ( - k1 INT, - k2 ARRAY<INT> +CREATE TABLE array_difference_test ( + id INT, + int_array ARRAY<INT>, + double_array ARRAY<DOUBLE> ) -duplicate key (k1) -distributed by hash(k1) buckets 1 -properties( - 'replication_num' = '1' +DUPLICATE KEY(id) +DISTRIBUTED BY HASH(id) BUCKETS 3 +PROPERTIES ( + "replication_num" = "1" ); -INSERT INTO array_type_table (k1, k2) VALUES -(0, []), -(1, [NULL]), -(2, [1, 2, 3]), -(3, [1, NULL, 3]), -(4, [0, 1, 2, 3, NULL, 4, 6]), -(5, [1, 2, 3, 4, 5, 4, 3, 2, 1]), -(6, [6, 7, 8]); -select *,array_difference(k2) from array_type_table; -``` -```text -+------+-----------------------------+---------------------------------+ -| k1 | k2 | array_difference(`k2`) | -+------+-----------------------------+---------------------------------+ -| 0 | [] | [] | -| 1 | [NULL] | [NULL] | -| 2 | [1, 2, 3] | [0, 1, 1] | -| 3 | [1, NULL, 3] | [0, NULL, NULL] | -| 4 | [0, 1, 2, 3, NULL, 4, 6] | [0, 1, 1, 1, NULL, NULL, 2] | -| 5 | [1, 2, 3, 4, 5, 4, 3, 2, 1] | [0, 1, 1, 1, 1, -1, -1, -1, -1] | -| 6 | [6, 7, 8] | [0, 1, 1] | -+------+-----------------------------+---------------------------------+ + +INSERT INTO array_difference_test VALUES +(1, [1, 3, 6, 10, 15], [1.1, 3.3, 6.6, 11.0, 16.5]), +(2, [10, 30, 60], [10.5, 41.0, 76.5]), +(3, [], []), +(4, NULL, NULL); +``` + +**查询示例：** + +int_array 的差值：每个位置的值为当前元素与前一个元素的差值，第一个元素为 0。 +```sql +SELECT array_difference(int_array) FROM array_difference_test WHERE id = 1; ++-----------------------------+ +| array_difference(int_array) | ++-----------------------------+ +| [0, 2, 3, 4, 5] | ++-----------------------------+ +``` + +double_array 的差值：浮点数数组的差值，结果为浮点数。 + +注意，第二个位置的结果是 2.1999999999999997，这是由于浮点数的二进制表示精度导致的微小误差（3.3 - 1.1 在二进制下无法精确表示为 2.2）。后面的 3.3、4.4、5.5 虽然看上去是“正常值”，其实也是二进制近似值，只是四舍五入后与十进制一致。这是所有基于 IEEE 754 浮点数的系统（包括 MySQL、Snowflake、Python、JavaScript 等）都会遇到的现象。 Review Comment: 还是需要的 可以在搜索的时候提高搜索率 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org For additional commands, e-mail: commits-h...@doris.apache.org
