csun5285 commented on code in PR #2671:
URL: https://github.com/apache/doris-website/pull/2671#discussion_r2242286334
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-count.md:
##########
@@ -5,95 +5,228 @@
}
---
-## 描述
+## array_count
+
+<version since="2.0.0">
-使用 lambda 表达式作为输入参数，对其他输入 ARRAY 参数的内部数据进行相应的表达式计算。返回使得 `lambda(array1[i],
...)` 返回值不为 0 的元素数量。如果找不到到满足此条件的元素，则返回 0。
+</version>
-lambda 表达式中输入的参数为 1 个或多个，必须和后面输入的数组列数一致，且所有输入的 array 的元素个数必须相同。在 lambda
中可以执行合法的标量函数，不支持聚合函数等。
+## 描述
+
+对数组中的元素应用 lambda 表达式，统计返回值不为 0 的元素个数。
## 语法
```sql
-ARRAY_COUNT(<arr>),
-ARRAY_COUNT(<lambda>, <arr> [ , <arr> ... ] )
+array_count(lambda, array1, ...)
```
-## 参数
+### 参数
+
+- `lambda`：lambda 表达式，用于对数组元素进行判断和计算
+- `array1, ...`：一个或多个 ARRAY<T> 类型参数
+
+**T 支持的类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
Review Comment:
所有类型都支持的话，可以不用特意写 T 支持的类型
##########
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:
这种不用写？
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-contains.md:
##########
@@ -1,50 +1,214 @@
---
{
- "title": "ARRAY_CONTAINS",
- "language": "zh-CN"
+ "title": "ARRAY_CONTAINS",
+ "language": "zh-CN"
}
---
## array_contains
-array_contains
+<version since="1.2.0">
+
+
+</version>
## 描述
+检查数组中是否包含指定的值。如果找到则返回 true，否则返回 false。如果数组为 NULL，则返回 NULL。
+
## 语法
-`BOOLEAN array_contains(ARRAY<T> arr, T value)`
+```sql
+array_contains(ARRAY<T> arr, T value)
+```
+
+### 参数
+
+- `arr`：ARRAY<T> 类型，要检查的数组。支持列名或常量值。
+- `value`：T 类型，要查找的值。类型必须与数组元素类型兼容。
+
+**T 支持的类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
Review Comment:
这种建议写不支持半结构化类型
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-contains.md:
##########
@@ -1,50 +1,214 @@
---
{
- "title": "ARRAY_CONTAINS",
- "language": "zh-CN"
+ "title": "ARRAY_CONTAINS",
+ "language": "zh-CN"
}
---
## array_contains
-array_contains
+<version since="1.2.0">
+
+
+</version>
## 描述
+检查数组中是否包含指定的值。如果找到则返回 true，否则返回 false。如果数组为 NULL，则返回 NULL。
+
## 语法
-`BOOLEAN array_contains(ARRAY<T> arr, T value)`
+```sql
+array_contains(ARRAY<T> arr, T value)
+```
+
+### 参数
+
+- `arr`：ARRAY<T> 类型，要检查的数组。支持列名或常量值。
+- `value`：T 类型，要查找的值。类型必须与数组元素类型兼容。
+
+**T 支持的类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
+- 字符串类型：CHAR、VARCHAR、STRING
+- 日期时间类型：DATE、DATETIME、DATEV2、DATETIMEV2
+- 布尔类型：BOOLEAN
+- IP 类型：IPV4、IPV6
+
+### 返回值
+
+返回类型：BOOLEAN
-判断数组中是否包含 value。返回结果如下：
+返回值含义：
+- true：如果数组中包含指定的值
+- false：如果数组中不包含指定的值
+- NULL：如果输入数组为 NULL
+返回值行为说明：
+
+1. 边界条件行为：
+ - 当输入数组为空时，返回 false
+ - 当输入数组为 NULL 时，返回 NULL
+ - 当数组元素类型与查找值类型不匹配时，返回 false
+ - 函数是 nullsafe 的
+ - 对数组元素中的 null 值：null 元素会被正常处理，可以查找数组中的 null 元素
+
+2. 异常值行为：
+ - 当数组元素是不支持的类型，返回不支持错误
+
+3. 返回 NULL 的情况：
+ - 当输入数组为 NULL
+
+**类型兼容性规则：**
Review Comment:
这种属于 T 类型的规则，不用在函数里面写
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-contains.md:
##########
@@ -1,50 +1,214 @@
---
{
- "title": "ARRAY_CONTAINS",
- "language": "zh-CN"
+ "title": "ARRAY_CONTAINS",
+ "language": "zh-CN"
}
---
## array_contains
-array_contains
+<version since="1.2.0">
+
+
+</version>
## 描述
+检查数组中是否包含指定的值。如果找到则返回 true，否则返回 false。如果数组为 NULL，则返回 NULL。
+
## 语法
-`BOOLEAN array_contains(ARRAY<T> arr, T value)`
+```sql
+array_contains(ARRAY<T> arr, T value)
+```
+
+### 参数
+
+- `arr`：ARRAY<T> 类型，要检查的数组。支持列名或常量值。
+- `value`：T 类型，要查找的值。类型必须与数组元素类型兼容。
+
+**T 支持的类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
+- 字符串类型：CHAR、VARCHAR、STRING
+- 日期时间类型：DATE、DATETIME、DATEV2、DATETIMEV2
+- 布尔类型：BOOLEAN
+- IP 类型：IPV4、IPV6
+
+### 返回值
+
+返回类型：BOOLEAN
-判断数组中是否包含 value。返回结果如下：
+返回值含义：
+- true：如果数组中包含指定的值
+- false：如果数组中不包含指定的值
+- NULL：如果输入数组为 NULL
+返回值行为说明：
+
+1. 边界条件行为：
+ - 当输入数组为空时，返回 false
+ - 当输入数组为 NULL 时，返回 NULL
+ - 当数组元素类型与查找值类型不匹配时，返回 false
+ - 函数是 nullsafe 的
+ - 对数组元素中的 null 值：null 元素会被正常处理，可以查找数组中的 null 元素
+
+2. 异常值行为：
+ - 当数组元素是不支持的类型，返回不支持错误
+
+3. 返回 NULL 的情况：
+ - 当输入数组为 NULL
+
+**类型兼容性规则：**
+1. **数值类型兼容性**：
+ - 整数类型之间可以进行比较（TINYINT、SMALLINT、INT、BIGINT、LARGEINT）
+ - 浮点数类型之间可以进行比较（FLOAT、DOUBLE）
+ - 十进制类型之间可以进行比较（DECIMAL32、DECIMAL64、DECIMAL128I、DECIMALV2、DECIMAL256）
+ - 整数和浮点数之间可以进行比较
+2. **字符串类型兼容性**：
+ - CHAR、VARCHAR、STRING 类型之间可以进行比较
+3. **日期时间类型兼容性**：
+ - DATE 和 DATEV2 之间可以进行比较
+ - DATETIME 和 DATETIMEV2 之间可以进行比较
+
+### 示例
+
+**建表示例**
+```sql
+CREATE TABLE array_contains_test (
+ id INT,
+ int_array ARRAY<INT>,
+ string_array ARRAY<STRING>
+)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 3
+PROPERTIES (
+ "replication_num" = "1"
+);
+
+-- 插入测试数据
+INSERT INTO array_contains_test VALUES
+(1, [1000, 2000, 3000], ['apple', 'banana', 'cherry']),
+(2, [], []),
+(3, NULL, NULL);
+(4, [1000, null, 3000], ['apple', null, 'cherry']);
```
-1 - value在数组arr中存在；
-0 - value不存在数组arr中；
-NULL - arr为NULL时。
+
+**查询示例：**
+
+检查数组中是否包含某个整数值:该示例返回 false，因为 5 不在 int_array 中。
+```sql
+SELECT array_contains(int_array, 5) FROM array_contains_test WHERE id = 1;
++-------------------------------+
+| array_contains(int_array, 5) |
++-------------------------------+
+| 0 |
++-------------------------------+
```
-## 举例
+检查字符串数组中是否包含某个字符串:该示例返回 true，因为 'banana' 在 string_array 中。
+```sql
+SELECT array_contains(string_array, 'banana') FROM array_contains_test WHERE
id = 1;
++------------------------------------------+
+| array_contains(string_array, 'banana') |
++------------------------------------------+
+| 1 |
++------------------------------------------+
+```
+
+当前是空数组。该示例返回 false，因为空数组里面没有值。
+```sql
+SELECT array_contains(int_array, 1000) FROM array_contains_test WHERE id = 2;
++----------------------------------+
+| array_contains(int_array, 1000) |
++----------------------------------+
+| 0 |
++----------------------------------+
+```
+
+当前是 NULL 数组，该示例返回 NULL。
+```sql
+SELECT array_contains(int_array, 1000) FROM array_contains_test WHERE id = 3;
++----------------------------------+
+| array_contains(int_array, 1000) |
++----------------------------------+
+| NULL |
++----------------------------------+
+```
+
+检查数组中是否包含 null
+在本例中，value_expr 参数为 null，且数组中没有 null 元素，因此返回 false。
+```sql
+SELECT array_contains([1, 2, 3], null);
++---------------------------------+
+| array_contains([1, 2, 3], null) |
++---------------------------------+
+| 0 |
++---------------------------------+
+```
+
+检查数组中是否包含 null
+在本例中，value_expr 参数为 null，且数组中包含 SQL null 值，因此返回 true。
+```sql
+SELECT array_contains([null, 1, 2], null);
++------------------------------------+
+| array_contains([null, 1, 2], null) |
++------------------------------------+
+| 1 |
++------------------------------------+
+```
+当查找值类型与数组元素类型不兼容，返回 false。
+```sql
+SELECT array_contains([1, 2, 3], 'string');
++-------------------------------------+
+| array_contains([1, 2, 3], 'string') |
++-------------------------------------+
+| 0 |
++-------------------------------------+
```
-mysql> SELECT id,c_array,array_contains(c_array, 5) FROM `array_test`;
-+------+-----------------+------------------------------+
-| id | c_array | array_contains(`c_array`, 5) |
-+------+-----------------+------------------------------+
-| 1 | [1, 2, 3, 4, 5] | 1 |
-| 2 | [6, 7, 8] | 0 |
-| 3 | [] | 0 |
-| 4 | NULL | NULL |
-+------+-----------------+------------------------------+
-mysql> select array_contains([null, 1], null);
-+--------------------------------------+
-| array_contains(ARRAY(NULL, 1), NULL) |
-+--------------------------------------+
-| 1 |
-+--------------------------------------+
-1 row in set (0.00 sec)
+当查找值类型无法和数组元素进行类型转换时, 会返回错误
+```
+SELECT array_contains([1, 2, 3], [4, 5, 6]);
+ERROR 1105 (HY000): errCode = 2, detailMessage = can not cast from origin type
ARRAY<TINYINT> to target type=TINYINT
+```
+
+不支持的复杂类型会报错。在本例中，数组为嵌套数组类型，返回不支持错误。
+```sql
+SELECT array_contains([[1,2],[2,3]], [1,2]);
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.6)[RUNTIME_ERROR]execute failed or unsupported types for function
array_contains(Array(Nullable(Array(Nullable(TINYINT)))),
Array(Nullable(TINYINT)))
+```
+
+### 注意事项
+
+性能考虑： 当处理大数组时，如果非常在意性能影响，可以使用倒排索引进行加速查询，但是有一些使用限制需要注意
+
+1. 建立array 倒排索引的属性只能是不分词索引
+2. array的元素类型 T 必须是满足能建立倒排索引的数据类型基础上才能对array 建立索引
+3. 查询条件参数 T 如果是 NULL 则无法利用索引进行加速
+
Review Comment:
4. 函数作为谓词过滤条件时才会进行索引加速
##########
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
+
+使用说明：
+- 函数会尝试将所有元素转换为兼容的数值类型进行差值计算。仅支持以下类型的直接计算：
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
