Map functions¶

Map functions are used to construct and modify data from map-based data structures (collections of key-value pairs).

element_at()¶

Returns the value associated with the specified key in a map.

Null behavior: general

Function signature¶

element_at(target_map, key) -> ANY

target_map: The target map from which to retrieve the value.
key: The key whose associated value is to be returned. Supports any predefined data type or constructed data type other than records and paths.

Notes¶

If the specified key does not exist in the map, the function returns null.
The data type of the key must be the same as the data type of the existing keys in the map.

Examples¶

Get value by key¶

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

Return:

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

Get value with null key¶

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

Return:

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

Key does not exist¶

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

Return:

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

map_append()¶

Appends a new key-value pair to an existing map.

Null behavior: general

Function signature¶

map_append(target_map, key, value) -> MAP

target_map: The target map to which the new key-value pair is to be appended.
key: The key to be appended. Supports any predefined data type or constructed data type other than records and paths.
value: The value to be appended. Supports any predefined data type or constructed data type other than records and paths.

Notes¶

If the specified key already exists in the map, the function returns the original map without modifying it. It does not override the existing value.
The data type of the key/value to be appended must be the same as the data type of the existing keys/values in the map.
You can append a key-value pair to an empty map (MAP{}) to create a new map containing a single entry.
Both the key and value can be null.

Examples¶

Append a non-null key-value pair¶

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

Return:

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

Append a null key-value pair¶

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

Return:

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

Append to an empty map¶

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

Return:

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

Append to a null map¶

RETURN map_append(null, 1, "a")

Return:

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

Append to a map with an existing key¶

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

Return:

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

map_replace()¶

Replaces the value associated with the specified key in a map.

Null behavior: general

Function signature¶

map_replace(target_map, key, value) -> MAP

target_map: The target map in which to replace the value.
key: The key whose associated value is to be replaced. Supports any predefined data type or constructed data type other than records and paths.
value: The new value to replace the existing value. Supports any predefined data type or constructed data type other than records and paths.

Notes¶

If the specified key does not exist in the map, an error is raised.
The data type of the key must be the same as the data type of the existing keys in the map.
The data type of the value must be the same as the data type of the existing values in the map.

Examples¶

Replace an existing value¶

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

Return:

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

Replace value with null key¶

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

Return:

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

Key does not exist (error)¶

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

Error:

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

Key type mismatch (error)¶

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

Error:

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

Value type mismatch (error)¶

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

Error:

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

map_keys()¶

Returns a list containing all keys from a map.

Null behavior: general

Function signature¶

map_keys(target_map) -> LIST

target_map: The target map from which to extract keys.

Examples¶

Get all keys¶

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

Return:

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

Get keys from a map with null key¶

RETURN map_keys(MAP{null:null})

Return:

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

Get keys from an empty map¶

RETURN map_keys(MAP{})

Return:

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

map_values()¶

Returns a list containing all values from a map.

Null behavior: general

Function signature¶

map_values(target_map) -> LIST

target_map: The target map from which to extract values.

Examples¶

Get all values¶

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

Return:

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

Get values from an empty map¶

RETURN map_values(MAP{})

Return:

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

map_union()¶

Returns the union of two maps.

Null behavior: general

Function signature¶

map_union(map1, map2) -> MAP

map1: The first map.
map2: The second map.

Notes¶

If the same key exists in both maps with the same value, the key-value pair is included in the result.
If the same key exists in both maps with different values, an error is raised.
Functionally equivalent to the || operator.

Examples¶

Union of two maps with different keys¶

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

Return:

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

Union with an empty map¶

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

Return:

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

Union with same key and same value¶

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

Return:

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

Union with same key but different values (error)¶

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

Error:

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

map_intersect()¶

Returns the intersection of two maps.

Null behavior: general

Function signature¶

map_intersect(map1, map2) -> MAP

map1: The first map.
map2: The second map.

Notes¶

Only key-value pairs where both the key and value are identical in both maps are included in the result.
If a key exists in both maps but with different values, it is not included in the result.

Examples¶

Intersection with matching key-value pairs¶

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

Return:

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

Intersection with same key but different values¶

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

Return:

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

map_except()¶

Returns the difference of two maps (elements in the first map that are not in the second map).

Null behavior: general

Function signature¶

map_except(map1, map2) -> MAP

map1: The first map.
map2: The second map.

Notes¶

A key-value pair is removed from the result only if both the key and value are identical in both maps.
If a key exists in both maps but with different values, it remains in the result.

Examples¶

Except with no matching keys¶

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

Return:

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

Except with same key but different values¶

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

Return:

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

Except with an empty first map¶

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

Return:

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

Except with matching key-value pairs¶

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

Return:

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

map_filter()¶

Returns a new map containing only the key-value pairs that satisfy the specified predicate.

Null behavior: general

Function signature¶

map_filter(target_map, predicate) -> MAP

target_map: The target map to filter.
predicate: A lambda expression (k, v) -> boolean_expression that defines the filter condition. k represents the key and v represents the value.

Notes¶

If the input map is null, the function returns null.
If the input map is empty, the function returns an empty map.
The predicate is applied to each key-value pair, and only pairs where the predicate evaluates to true are included in the result.

Examples¶

Filter out null keys¶

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

Return:

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

Filter by value (keep non-null values)¶

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

Return:

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

Filter by both key and value¶

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

Return:

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

Filter with predicate always true¶

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

Return:

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

Filter by value string¶

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

Return:

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

Filter with captured variable¶

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

Return:

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

Filter null input¶

RETURN map_filter(NULL, (k, v) -> k > 1)

Return:

+------------------------------------+
| map_filter(NULL, (k, v) -> k > 1)  |
+------------------------------------+
| null                               |
+------------------------------------+

map_remove()¶

Removes the key-value pair with the specified key from a map.

Null behavior: general

Function signature¶

map_remove(target_map, key) -> MAP

target_map: The target map from which to remove the key-value pair.
key: The key of the key-value pair to be removed. Supports any predefined data type or constructed data type other than records and paths.

Notes¶

If the specified key does not exist in the map, the function returns the original map without modification.
The data type of the key must be the same as the data type of the existing keys in the map.

Examples¶

Remove an existing key¶

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

Return:

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

Remove a non-existent key¶

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

Return:

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

Remove from an empty map¶

RETURN map_remove(MAP{}, 1)

Return:

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

Key type mismatch (error)¶

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

Error:

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

remove_nulls()¶

Removes key-value pairs where both the key and value are null from a map.

Null behavior: general

Function signature¶

remove_nulls(target_map) -> MAP

target_map: The target map from which to remove null key-value pairs.

Notes¶

Only removes key-value pairs where both the key and value are null.
Key-value pairs where only the key or only the value is null are retained.

Examples¶

Remove null key-value pair¶

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

Return:

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

Retain pairs where only key or value is null¶

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

Return:

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