Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/map/
Documentation version: v5.3.2

# Map functions

Map functions are used to construct and modify data from [map](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/map-type/)-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}                   |
+-----------------------------------+

````