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

# 映射函数

映射函数用于构建及修改基于[映射（Map）](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/map-type/)的数据结构（键值对的集合）中的数据。

## element_at()

返回映射中指定键对应的值。

NULL 行为：通用

### 函数签名

````
element_at(target_map, key) -> ANY

````

- `target_map`：要从中获取值的目标映射。
- `key`：要获取对应值的键。支持除记录和路径以外的任何预定义数据类型或复合数据类型。

### 说明

- 如果指定的键在映射中不存在，函数返回`null`。
- 键的数据类型必须与映射中现有键的数据类型相同。

### 示例

#### 通过键获取值

````
RETURN element_at(MAP{1:"a", 2:"b"}, 1)

````

返回：

````
+----------------------------------+
| element_at(MAP{1:"a", 2:"b"}, 1) |
+----------------------------------+
| a                                |
+----------------------------------+

````

#### 获取 NULL 键对应的值

````
RETURN element_at(MAP{null:"a"}, null)

````

返回：

````
+----------------------------------+
| element_at(MAP{null:"a"}, null)  |
+----------------------------------+
| a                                |
+----------------------------------+

````

#### 键不存在

````
RETURN element_at(MAP{1:"a"}, 2)

````

返回：

````
+-----------------------------+
| element_at(MAP{1:"a"}, 2)   |
+-----------------------------+
| null                        |
+-----------------------------+

````

## map_append()

向已有的映射追加一个新的键值。

NULL 行为：通用

### 函数签名

````
map_append(target_map, key, value) -> MAP

````

- `target_map`：要追加键值对的目标映射。
- `key`：要追加的键。支持任意预定义数据类型，或除记录和路径之外的复合数据类型。
- `value`：要追加的值。支持任意预定义数据类型，或除记录和路径之外的复合数据类型。

### 使用说明

- 如果指定的键在映射中已存在，该函数不进行任何修改返回原映射，不会覆盖已有的值。
- 待追加键/值的数据类型必须与映射中现有键/值的数据类型一致。
- 可以向空映射（`MAP{}`）追加一个键值对，以创建只包含一个条目的新映射。
- 键和值都可以为`null`。

### 示例

#### 追加非 NULL 键值对

````
RETURN map_append(MAP{1:"a"}, 2, "b")

````

返回：

````
+--------------------------------+
| map_append(MAP{1:"a"}, 2, "b") |
+--------------------------------+
| {1:a,2:b}                      |
+--------------------------------+

````

#### 追加 NULL 键值对

````
RETURN map_append(MAP{1:"a", 2:"b"}, null, null)

````

返回：

````
+-------------------------------------------+
| map_append(MAP{1:"a", 2:"b"}, null, null) |
+-------------------------------------------+
| {1:a,2:b,null:null}                       |
+-------------------------------------------+

````

#### 向空映射追加

````
RETURN map_append(MAP{}, 1, "a")

````

返回：

````
+---------------------------+
| map_append(MAP{}, 1, "a") |
+---------------------------+
| {1:a}                     |
+---------------------------+

````

#### 向 NULL 映射追加

````
RETURN map_append(null, 1, "a")

````

返回：

````
+--------------------------+
| map_append(null, 1, "a") |
+--------------------------+
| null                     |
+--------------------------+

````

#### 向含有同名键的映射追加

````
RETURN map_append(MAP{true: "a"}, true, "b")

````

返回：

````
+---------------------------------------+
| map_append(MAP{true: "a"}, true, "b") |
+---------------------------------------+
| {true:a}                              |
+---------------------------------------+

````

## map_replace()

替换映射中指定键对应的值。

NULL 行为：通用

### 函数签名

````
map_replace(target_map, key, value) -> MAP

````

- `target_map`：要替换值的目标映射。
- `key`：要替换对应值的键。支持除记录和路径以外的任何预定义数据类型或复合数据类型。
- `value`：用于替换现有值的新值。支持除记录和路径以外的任何预定义数据类型或复合数据类型。

### 说明

- 如果指定的键在映射中不存在，会抛出错误。
- 键的数据类型必须与映射中现有键的数据类型相同。
- 值的数据类型必须与映射中现有值的数据类型相同。

### 示例

#### 替换现有值

````
RETURN map_replace(MAP{1:"old", 2:"b"}, 1, "new")

````

返回：

````
+--------------------------------------------+
| map_replace(MAP{1:"old", 2:"b"}, 1, "new") |
+--------------------------------------------+
| {1:new,2:b}                                |
+--------------------------------------------+

````

#### 替换 NULL 键对应的值

````
RETURN map_replace(MAP{null:"a"}, null, "b")

````

返回：

````
+---------------------------------------+
| map_replace(MAP{null:"a"}, null, "b") |
+---------------------------------------+
| {null:b}                              |
+---------------------------------------+

````

#### 键不存在（报错）

````
RETURN map_replace(MAP{1:"a", 2:"b"}, 3, "c")

````

报错：

````
[NR003]: Invalid function argument: map_replace: key not found

````

#### 键类型不匹配（报错）

````
RETURN map_replace(MAP{1:"a"}, "key", "b")

````

报错：

````
[NR006]: Resolve function failed: `The map element key type mismatch: INT32 vs STRING`

````

#### 值类型不匹配（报错）

````
RETURN map_replace(MAP{1:"a"}, 1, 100)

````

报错：

````
[NR006]: Resolve function failed: `The map element value type mismatch: STRING vs INT32`

````

## map_keys()

返回包含映射中所有键的列表。

NULL 行为：通用

### 函数签名

````
map_keys(target_map) -> LIST

````

- `target_map`：要从中提取键的目标映射。

### 示例

#### 获取所有键

````
RETURN map_keys(MAP{1:"a", 2:"b"})

````

返回：

````
+-----------------------------+
| map_keys(MAP{1:"a", 2:"b"}) |
+-----------------------------+
| [1,2]                       |
+-----------------------------+

````

#### 从包含 NULL 键的映射中获取键

````
RETURN map_keys(MAP{null:null})

````

返回：

````
+---------------------------+
| map_keys(MAP{null:null})  |
+---------------------------+
| [null]                    |
+---------------------------+

````

#### 从空映射中获取键

````
RETURN map_keys(MAP{})

````

返回：

````
+------------------+
| map_keys(MAP{})  |
+------------------+
| []               |
+------------------+

````

## map_values()

返回包含映射中所有值的列表。

NULL 行为：通用

### 函数签名

````
map_values(target_map) -> LIST

````

- `target_map`：要从中提取值的目标映射。

### 示例

#### 获取所有值

````
RETURN map_values(MAP{1:"a", 2:"a"})

````

返回：

````
+-------------------------------+
| map_values(MAP{1:"a", 2:"a"}) |
+-------------------------------+
| [a,a]                         |
+-------------------------------+

````

#### 从空映射中获取值

````
RETURN map_values(MAP{})

````

返回：

````
+--------------------+
| map_values(MAP{})  |
+--------------------+
| []                 |
+--------------------+

````

## map_union()

返回两个映射的并集。

NULL 行为：通用

### 函数签名

````
map_union(map1, map2) -> MAP

````

- `map1`：第一个映射。
- `map2`：第二个映射。

### 说明

- 如果两个映射中存在相同的键且值也相同，该键值对会包含在结果中。
- 如果两个映射中存在相同的键但值不同，会抛出错误。
- 功能与`||`运算符相同。

### 示例

#### 合并两个键不同的映射

````
RETURN map_union(MAP{1:"a", 2:"b"}, MAP{3:"c", 4:"d"})

````

返回：

````
+-------------------------------------------------+
| map_union(MAP{1:"a", 2:"b"}, MAP{3:"c", 4:"d"}) |
+-------------------------------------------------+
| {1:a,2:b,3:c,4:d}                               |
+-------------------------------------------------+

````

#### 与空映射合并

````
RETURN map_union(MAP{}, MAP{1:"a"})

````

返回：

````
+-------------------------------+
| map_union(MAP{}, MAP{1:"a"})  |
+-------------------------------+
| {1:a}                         |
+-------------------------------+

````

#### 合并具有相同键和相同值的映射

````
RETURN map_union(MAP{1:"a"}, MAP{1:"a"})

````

返回：

````
+-----------------------------------+
| map_union(MAP{1:"a"}, MAP{1:"a"}) |
+-----------------------------------+
| {1:a}                             |
+-----------------------------------+

````

#### 合并具有相同键但值不同的映射（报错）

````
RETURN map_union(MAP{null:"a"}, MAP{null:"b"})

````

报错：

````
[NR003]: Invalid function argument: map_union: duplicate key with different value

````

## map_intersect()

返回两个映射的交集。

NULL 行为：通用

### 函数签名

````
map_intersect(map1, map2) -> MAP

````

- `map1`：第一个映射。
- `map2`：第二个映射。

### 说明

- 只有当键和值在两个映射中都完全相同时，该键值对才会包含在结果中。
- 如果一个键在两个映射中都存在但值不同，则不会包含在结果中。

### 示例

#### 取具有相同键值对的交集

````
RETURN map_intersect(MAP{1:"a", 2:"b"}, MAP{1:"a", 4:"d"})

````

返回：

````
+-----------------------------------------------------+
| map_intersect(MAP{1:"a", 2:"b"}, MAP{1:"a", 4:"d"}) |
+-----------------------------------------------------+
| {1:a}                                               |
+-----------------------------------------------------+

````

#### 取具有相同键但值不同的交集

````
RETURN map_intersect(MAP{null:"a"}, MAP{null:"b"})

````

返回：

````
+---------------------------------------------+
| map_intersect(MAP{null:"a"}, MAP{null:"b"}) |
+---------------------------------------------+
| {}                                          |
+---------------------------------------------+

````

## map_except()

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

NULL 行为：通用

### 函数签名

````
map_except(map1, map2) -> MAP

````

- `map1`：第一个映射。
- `map2`：第二个映射。

### 说明

- 只有当键和值在两个映射中都完全相同时，该键值对才会从结果中移除。
- 如果一个键在两个映射中都存在但值不同，该键值对会保留在结果中。

### 示例

#### 取没有相同键的差集

````
RETURN map_except(MAP{1:"a", 2:"b"}, MAP{3:"c", 4:"d"})

````

返回：

````
+--------------------------------------------------+
| map_except(MAP{1:"a", 2:"b"}, MAP{3:"c", 4:"d"}) |
+--------------------------------------------------+
| {1:a,2:b}                                        |
+--------------------------------------------------+

````

#### 取具有相同键但值不同的差集

````
RETURN map_except(MAP{null:"a"}, MAP{null:"b"})

````

返回：

````
+------------------------------------------+
| map_except(MAP{null:"a"}, MAP{null:"b"}) |
+------------------------------------------+
| {null:a}                                 |
+------------------------------------------+

````

#### 第一个映射为空时取差集

````
RETURN map_except(MAP{}, MAP{1:"a"})

````

返回：

````
+-------------------------------+
| map_except(MAP{}, MAP{1:"a"}) |
+-------------------------------+
| {}                            |
+-------------------------------+

````

#### 取具有相同键值对的差集

````
RETURN map_except(MAP{1:"a"}, MAP{1:"a"})

````

返回：

````
+------------------------------------+
| map_except(MAP{1:"a"}, MAP{1:"a"}) |
+------------------------------------+
| {}                                 |
+------------------------------------+

````

## map_filter()

返回一个新映射，其中只包含满足指定谓词条件的键值对。

NULL 行为：通用

### 函数签名

````
map_filter(target_map, predicate) -> MAP

````

- `target_map`：要过滤的目标映射。
- `predicate`：Lambda 表达式`(k, v) -> boolean_expression`，用于定义过滤条件。`k`表示键，`v`表示值。

### 说明

- 如果输入映射为`null`，函数返回`null`。
- 如果输入映射为空，函数返回空映射。
- 谓词会应用于每个键值对，只有谓词计算结果为`true`的键值对才会包含在结果中。

### 示例

#### 过滤掉 NULL 键

````
RETURN map_filter(MAP{1:"a", 2:"b", null:null}, (k, v) -> k IS NOT NULL)

````

返回：

````
+-------------------------------------------------------------------+
| map_filter(MAP{1:"a", 2:"b", null:null}, (k, v) -> k IS NOT NULL) |
+-------------------------------------------------------------------+
| {1:a,2:b}                                                         |
+-------------------------------------------------------------------+

````

#### 按值过滤（保留非空值）

````
RETURN map_filter(MAP{1:"a", 2:null, 3:"c"}, (k, v) -> v IS NOT NULL)

````

返回：

````
+----------------------------------------------------------------+
| map_filter(MAP{1:"a", 2:null, 3:"c"}, (k, v) -> v IS NOT NULL) |
+----------------------------------------------------------------+
| {1:a,3:c}                                                      |
+----------------------------------------------------------------+

````

#### 同时按键和值过滤

````
RETURN map_filter(MAP{1:"a", 2:"b", 3:"a", 4:"x"}, (k, v) -> k >= 2 AND v <> "a")

````

返回：

````
+----------------------------------------------------------------------------+
| map_filter(MAP{1:"a", 2:"b", 3:"a", 4:"x"}, (k, v) -> k >= 2 AND v <> "a") |
+----------------------------------------------------------------------------+
| {2:b,4:x}                                                                  |
+----------------------------------------------------------------------------+

````

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

````
RETURN map_filter(MAP{1:"a", 2:"b"}, (k, v) -> true)

````

返回：

````
+-----------------------------------------------+
| map_filter(MAP{1:"a", 2:"b"}, (k, v) -> true) |
+-----------------------------------------------+
| {1:a,2:b}                                     |
+-----------------------------------------------+

````

#### 按字符串值过滤

````
RETURN map_filter(MAP{"x":"yes", "y":"no", "z":"yes"}, (k, v) -> v = "yes")

````

返回：

````
+----------------------------------------------------------------------+
| map_filter(MAP{"x":"yes", "y":"no", "z":"yes"}, (k, v) -> v = "yes") |
+----------------------------------------------------------------------+
| {x:yes,z:yes}                                                        |
+----------------------------------------------------------------------+

````

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

````
FOR i IN [0, 5, 2]
RETURN map_filter(MAP{1:"a", 2:"b", 3:"c"}, (k, v) -> k > i)

````

返回：

````
+--------------------------------------------------------------+
| map_filter(MAP{1:"a", 2:"b", 3:"c"}, (k, v) -> k > i)        |
+--------------------------------------------------------------+
| {1:a,2:b,3:c}                                                |
| {}                                                           |
| {3:c}                                                        |
+--------------------------------------------------------------+

````

## map_remove()

从映射中移除指定键对应的键值对。

NULL 行为：通用

### 函数签名

````
map_remove(target_map, key) -> MAP

````

- `target_map`：要从中移除键值对的目标映射。
- `key`：要移除的键值对的键。支持除记录和路径以外的任何预定义数据类型或复合数据类型。

### 说明

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

### 示例

#### 移除已存在的键

````
RETURN map_remove(MAP{1:"a", 2:"b"}, 1)

````

返回：

````
+----------------------------------+
| map_remove(MAP{1:"a", 2:"b"}, 1) |
+----------------------------------+
| {2:b}                            |
+----------------------------------+

````

#### 移除不存在的键

````
RETURN map_remove(MAP{null:"a"}, 1)

````

返回：

````
+------------------------------+
| map_remove(MAP{null:"a"}, 1) |
+------------------------------+
| {null:a}                     |
+------------------------------+

````

#### 从空映射中移除

````
RETURN map_remove(MAP{}, 1)

````

返回：

````
+-----------------------+
| map_remove(MAP{}, 1)  |
+-----------------------+
| {}                    |
+-----------------------+

````

#### 键类型不匹配（报错）

````
RETURN map_remove(MAP{1:"a"}, "key")

````

报错：

````
[NR006]: Resolve function failed: `The map element key type mismatch: INT32 vs STRING`

````

## remove_nulls()

从映射中移除键和值都为`null`的键值对。

NULL 行为：通用

### 函数签名

````
remove_nulls(target_map) -> MAP

````

- `target_map`：要从中移除空键值对的目标映射。

### 说明

- 只移除键和值都为`null`的键值对。
- 只有键为`null`或只有值为`null`的键值对会被保留。

### 示例

#### 移除空键值对

````
RETURN remove_nulls(MAP{1:"a", 2:"b", null:null})

````

返回：

````
+--------------------------------------------+
| remove_nulls(MAP{1:"a", 2:"b", null:null}) |
+--------------------------------------------+
| {1:a,2:b}                                  |
+--------------------------------------------+

````

#### 保留只有键或值为 NULL 的键值对

````
RETURN remove_nulls(MAP{null:1, 2:null})

````

返回：

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

````