映射函数¶
映射函数用于构建及修改基于映射（Map）的数据结构（键值对的集合）中的数据。
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} |
+-----------------------------------+