Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/set/
Documentation version: v5.3.2

# 集合函数

集合函数用于构建和修改基于[集合（Set）](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/set-type/) 数据结构（不包含重复元素的集合）的数据。

## set_append()

向现有集合中追加一个新元素。

NULL 行为：通用

### 函数签名

````
set_append(target_set, value) -> SET

````

- `target_set`：要追加新元素的目标集合。
- `value`：要追加的值。支持除记录和路径以外的任何预定义数据类型或复合数据类型。

### 说明

- 如果指定的值已存在于集合中，函数返回原集合而不进行修改（集合不允许重复元素）。
- 要追加的值的数据类型必须与集合中现有元素的数据类型相同。
- 可以向空集合（`SET{}`）追加元素，从而创建一个包含单个元素的新集合。
- 值可以是`null`。

### 示例

#### 追加新元素

````
RETURN set_append(SET{1, 2, 3}, 4)

````

返回：

````
+-----------------------------+
| set_append(SET{1, 2, 3}, 4) |
+-----------------------------+
| {1,2,3,4}                   |
+-----------------------------+

````

#### 追加已存在的元素

````
RETURN set_append(SET{null}, null)

````

返回：

````
+------------------------------+
| set_append(SET{null}, null)  |
+------------------------------+
| {null}                       |
+------------------------------+

````

#### 追加 null 值

````
RETURN set_append(SET{1}, null)

````

返回：

````
+--------------------------+
| set_append(SET{1}, null) |
+--------------------------+
| {1,null}                 |
+--------------------------+

````

#### 向空集合追加

````
RETURN set_append(SET{}, null)

````

返回：

````
+--------------------------+
| set_append(SET{}, null)  |
+--------------------------+
| {null}                   |
+--------------------------+

````

## set_union()

返回两个集合的并集。

NULL 行为：通用

### 函数签名

````
set_union(set1, set2) -> SET

````

- `set1`：第一个集合。
- `set2`：第二个集合。

### 说明

- 返回包含两个集合中所有唯一元素的新集合。
- 功能与`||`运算符相同。
- 如果任一参数为`null`，结果取决于具体实现。

### 示例

#### 合并两个集合

````
RETURN set_union(SET{1, 2, 3}, SET{3, 4, 5})

````

返回：

````
+---------------------------------------+
| set_union(SET{1, 2, 3}, SET{3, 4, 5}) |
+---------------------------------------+
| {5,4,3,2,1}                           |
+---------------------------------------+

````

#### 与空集合合并

````
RETURN set_union(SET{}, SET{1, 2})

````

返回：

````
+-----------------------------+
| set_union(SET{}, SET{1, 2}) |
+-----------------------------+
| {2,1}                       |
+-----------------------------+

````

#### 合并包含 null 的集合

````
RETURN set_union(SET{null, null}, SET{null})

````

返回：

````
+----------------------------------------+
| set_union(SET{null, null}, SET{null})  |
+----------------------------------------+
| {null}                                 |
+----------------------------------------+

````

## set_intersect()

返回两个集合的交集。

NULL 行为：通用

### 函数签名

````
set_intersect(set1, set2) -> SET

````

- `set1`：第一个集合。
- `set2`：第二个集合。

### 说明

- 返回同时存在于两个集合中的元素组成的新集合。

### 示例

#### 取两个集合的交集

````
RETURN set_intersect(SET{1, 2, 3}, SET{2, 3, 4})

````

返回：

````
+-------------------------------------------+
| set_intersect(SET{1, 2, 3}, SET{2, 3, 4}) |
+-------------------------------------------+
| {3,2}                                     |
+-------------------------------------------+

````

#### 无共同元素

````
RETURN set_intersect(SET{1, 2, 3}, SET{4, 5, 6})

````

返回：

````
+-------------------------------------------+
| set_intersect(SET{1, 2, 3}, SET{4, 5, 6}) |
+-------------------------------------------+
| {}                                        |
+-------------------------------------------+

````

#### 与 null 取交集

````
RETURN set_intersect(SET{1, 2, 3}, null)

````

返回：

````
+-----------------------------------+
| set_intersect(SET{1, 2, 3}, null) |
+-----------------------------------+
| null                              |
+-----------------------------------+

````

#### 包含 null 元素的交集

````
'''
LET a = set_intersect(SET{1, 2, 3, null}, SET{1, 2, 3, 4})
RETURN size(a)
'''

````

返回：

````
+---------+
| size(a) |
+---------+
| 3       |
+---------+

````

## set_except()

返回两个集合的差集（第一个集合中不在第二个集合中的元素）。

NULL 行为：通用

### 函数签名

````
set_except(set1, set2) -> SET

````

- `set1`：第一个集合。
- `set2`：第二个集合。

### 说明

- 返回存在于第一个集合但不存在于第二个集合中的元素组成的新集合。

### 示例

#### 取差集

````
RETURN set_except(SET{1, 2, 3}, SET{2, 3, 4})

````

返回：

````
+----------------------------------------+
| set_except(SET{1, 2, 3}, SET{2, 3, 4}) |
+----------------------------------------+
| {1}                                    |
+----------------------------------------+

````

#### 第一个集合为子集

````
RETURN set_except(SET{1, 2, 3}, SET{1, 2, 3, 4})

````

返回：

````
+-------------------------------------------+
| set_except(SET{1, 2, 3}, SET{1, 2, 3, 4}) |
+-------------------------------------------+
| {}                                        |
+-------------------------------------------+

````

#### 包含 null 元素的差集

````
RETURN set_except(SET{1, 2, 3, null}, SET{4})

````

返回：

````
+----------------------------------------+
| set_except(SET{1, 2, 3, null}, SET{4}) |
+----------------------------------------+
| {null,3,2,1}                           |
+----------------------------------------+

````

## set_sum()

返回集合中所有数值元素的总和。

NULL 行为：通用

### 函数签名

````
set_sum(target_set) -> NUMERIC

````

- `target_set`：要计算总和的目标集合。

### 说明

- 仅支持数值类型和 [NULL 类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/null-type/)。
- `null`值在计算时被忽略。
- 如果集合只包含`null`，返回`0`。
- 如果集合包含`NaN`，返回`NaN`。

### 示例

#### 计算数值总和

````
RETURN set_sum(SET{1.0M, 2M})

````

返回：

````
+------------------------+
| set_sum(SET{1.0M, 2M}) |
+------------------------+
| 3.0                    |
+------------------------+

````

#### 只包含 null 的集合

````
RETURN set_sum(SET{null})

````

返回：

````
+--------------------+
| set_sum(SET{null}) |
+--------------------+
| 0                  |
+--------------------+

````

#### 包含 null 的数值集合

````
RETURN set_sum(SET{1, null})

````

返回：

````
+-----------------------+
| set_sum(SET{1, null}) |
+-----------------------+
| 1                     |
+-----------------------+

````

#### 包含 NaN 的集合

````
RETURN set_sum(SET{1.0M, 2M, NAN})

````

返回：

````
+-----------------------------+
| set_sum(SET{1.0M, 2M, NAN}) |
+-----------------------------+
| NaN                         |
+-----------------------------+

````

#### 同时包含 NaN 和 null 的集合

````
RETURN set_sum(SET{1.0M, 2M, NAN, NULL})

````

返回：

````
+-----------------------------------+
| set_sum(SET{1.0M, 2M, NAN, NULL}) |
+-----------------------------------+
| NaN                               |
+-----------------------------------+

````

## set_max()

返回集合中的最大值。有关值之间比较规则的更多信息，请参见[比较谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/)。

NULL 行为：通用

### 函数签名

````
set_max(target_set) -> NUMERIC | NULL

````

- `target_set`：要查找最大值的目标集合。

### 说明

- 仅支持数值类型和 [NULL 类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/null-type/)。
- 如果集合包含`null`，返回`null`。

### 示例

#### 获取最大值

````
RETURN set_max(SET{1, 2, 3.0M})

````

返回：

````
+--------------------------+
| set_max(SET{1, 2, 3.0M}) |
+--------------------------+
| 3.0                      |
+--------------------------+

````

#### 只包含 null 的集合

````
RETURN set_max(SET{null})

````

返回：

````
+--------------------+
| set_max(SET{null}) |
+--------------------+
| null               |
+--------------------+

````

#### 包含 NaN 的集合

````
RETURN set_max(SET{1.0M, 2M, NAN})

````

返回：

````
+-----------------------------+
| set_max(SET{1.0M, 2M, NAN}) |
+-----------------------------+
| NaN                         |
+-----------------------------+

````

#### 包含 null 和 NaN 的集合

````
RETURN set_max(SET{1.0M, NULL, 2M, NAN})

````

返回：

````
+-----------------------------------+
| set_max(SET{1.0M, NULL, 2M, NAN}) |
+-----------------------------------+
| null                              |
+-----------------------------------+

````

#### 负数集合

````
RETURN set_max(SET{-10.8, -10.7, -10.6})

````

返回：

````
+-----------------------------------+
| set_max(SET{-10.8, -10.7, -10.6}) |
+-----------------------------------+
| -10.6                             |
+-----------------------------------+

````

## set_min()

返回集合中的最小值。有关值之间比较规则的更多信息，请参见[比较谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/)。

NULL 行为：通用

### 函数签名

````
set_min(target_set) -> NUMERIC | NULL

````

- `target_set`：要查找最小值的目标集合。

### 说明

- 仅支持数值类型和 [NULL 类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/null-type/)。
- 如果集合包含 null，返回 null。

### 示例

#### 获取最小值

````
RETURN set_min(SET{1, 2, 3.0M})

````

返回：

````
+--------------------------+
| set_min(SET{1, 2, 3.0M}) |
+--------------------------+
| 1                        |
+--------------------------+

````

#### 只包含 null 的集合

````
RETURN set_min(SET{null})

````

返回：

````
+--------------------+
| set_min(SET{null}) |
+--------------------+
| null               |
+--------------------+

````

#### 包含 NaN 的集合

````
RETURN set_min(SET{1.0M, 2M, NAN})

````

返回：

````
+-----------------------------+
| set_min(SET{1.0M, 2M, NAN}) |
+-----------------------------+
| 1.0                         |
+-----------------------------+

````

#### 包含 null 和 NaN 的集合

````
RETURN set_min(SET{1.0M, NULL, 2M, NAN})

````

返回：

````
+-----------------------------------+
| set_min(SET{1.0M, NULL, 2M, NAN}) |
+-----------------------------------+
| null                              |
+-----------------------------------+

````

#### 负数集合

````
RETURN set_min(SET{-10.8, -10.7, -10.6})

````

返回：

````
+-----------------------------------+
| set_min(SET{-10.8, -10.7, -10.6}) |
+-----------------------------------+
| -10.8                             |
+-----------------------------------+

````

## set_filter()

返回一个新集合，其中只包含满足指定条件的元素。

NULL 行为：通用

### 函数签名

````
set_filter(target_set, predicate) -> SET

````

- `target_set`：要过滤的目标集合。
- `predicate`：Lambda 表达式`x -> boolean_expression`，用于定义过滤条件。`x`表示集合中的元素。

### 说明

- 如果输入集合为`null`，函数返回`null`。
- 如果输入集合为空，函数返回空集合。
- 谓词会应用于每个元素，只有谓词计算结果为`true`的元素才会包含在结果中。

### 示例

#### 过滤掉 null 元素

````
RETURN set_filter(SET{1, 2, 3, null}, x -> x IS NOT NULL)

````

返回：

````
+----------------------------------------------------+
| set_filter(SET{1, 2, 3, null}, x -> x IS NOT NULL) |
+----------------------------------------------------+
| {1,2,3}                                            |
+----------------------------------------------------+

````

#### 按数值条件过滤

````
RETURN set_filter(SET{1, 2, 3, 4}, x -> x >= 2 AND x <> 3)

````

返回：

````
+-----------------------------------------------------+
| set_filter(SET{1, 2, 3, 4}, x -> x >= 2 AND x <> 3) |
+-----------------------------------------------------+
| {2,4}                                               |
+-----------------------------------------------------+

````

#### 谓词始终为 true 时过滤

````
RETURN set_filter(SET{1, 2}, x -> true)

````

返回：

````
+----------------------------------+
| set_filter(SET{1, 2}, x -> true) |
+----------------------------------+
| {1,2}                            |
+----------------------------------+

````

#### 按字符串过滤

````
RETURN set_filter(SET{"yes", "no", "yes"}, x -> x = "yes")

````

返回：

````
+-----------------------------------------------------+
| set_filter(SET{"yes", "no", "yes"}, x -> x = "yes") |
+-----------------------------------------------------+
| {yes}                                               |
+-----------------------------------------------------+

````

#### 使用捕获变量过滤

````
'''
FOR i IN [0, 5, 2]
RETURN set_filter(SET{1, 2, 3}, x -> x > i)
'''

````

返回：

````
+--------------------------------------+
| set_filter(SET{1, 2, 3}, x -> x > i) |
+--------------------------------------+
| {3,2,1}                              |
| {}                                   |
| {3}                                  |
+--------------------------------------+

````

#### 使用 LET 变量过滤

````
'''
LET threshold = 2
FOR s IN [SET{1, 2}, SET{1, 2, 3}]
RETURN set_filter(s, x -> x >= threshold)
'''

````

返回：

````
+------------------------------------+
| set_filter(s, x -> x >= threshold) |
+------------------------------------+
| {2}                                |
| {3,2}                              |
+------------------------------------+

````

#### 过滤包含 null 和空集合的输入

````
'''
FOR s IN [SET{-1}, NULL, SET{}, SET{2}]
RETURN set_filter(s, x -> x > 0)
'''

````

返回：

````
+---------------------------+
| set_filter(s, x -> x > 0) |
+---------------------------+
| {}                        |
| null                      |
| {}                        |
| {2}                       |
+---------------------------+

````

#### 过滤 null 输入

````
RETURN set_filter(NULL, x -> x > 1)

````

返回：

````
+------------------------------+
| set_filter(NULL, x -> x > 1) |
+------------------------------+
| null                         |
+------------------------------+

````

## set_remove()

从集合中移除指定的元素。

NULL 行为：通用

### 函数签名

````
set_remove(target_set, value) -> SET

````

- `target_set`：要从中移除元素的目标集合。
- `value`：要移除的值。支持除记录和路径以外的任何预定义数据类型或复合数据类型。

### 说明

- 如果指定的值在集合中不存在，函数返回原集合而不进行修改。
- 值的数据类型必须与集合中现有元素的数据类型相同。

### 示例

#### 移除已存在的元素

````
RETURN set_remove(SET{1, 2, 3}, 1)

````

返回：

````
+-----------------------------+
| set_remove(SET{1, 2, 3}, 1) |
+-----------------------------+
| {3,2}                       |
+-----------------------------+

````

#### 移除不存在的元素

````
RETURN set_remove(SET{null}, 1)

````

返回：

````
+--------------------------+
| set_remove(SET{null}, 1) |
+--------------------------+
| {null}                   |
+--------------------------+

````

#### 从空集合中移除

````
RETURN set_remove(SET{}, 1)

````

返回：

````
+----------------------+
| set_remove(SET{}, 1) |
+----------------------+
| {}                   |
+----------------------+

````

## remove_nulls()

从集合中移除所有`null`值。

NULL 行为：通用

### 函数签名

````
remove_nulls(target_set) -> SET

````

- `target_set`：要从中移除 null 值的目标集合。

### 说明

- 移除集合中所有值为`null`的元素。
- 如果集合只包含`null`，返回空集合。

### 示例

#### 移除 NULL 值

````
RETURN remove_nulls(SET{1, 2, null})

````

返回：

````
+-------------------------------+
| remove_nulls(SET{1, 2, null}) |
+-------------------------------+
| {2,1}                         |
+-------------------------------+

````

#### 只包含 null 的集合

````
RETURN remove_nulls(SET{null})

````

返回：

````
+-------------------------+
| remove_nulls(SET{null}) |
+-------------------------+
| {}                      |
+-------------------------+

````