map

The map module offers a versatile toolkit for manipulating collections of key-value pairs, enabling advanced data operations within a graph database context.

Source code

Trait	Value
Module type	util
Implementation	C++
Graph direction	directed/undirected
Edge weights	weighted/unweighted
Parallelism	sequential

Functions

`remove_key()`

The procedure removes the specified key and its corresponding value from the input map. If the key does not exist in the input map, it will be ignored. Additionally, when the recursive config is enabled, the key will also be removed from any inner maps that are part of the input map.

Input:

map: Map ➡ The map from which the key will be removed (a node or relationship may be passed; its properties are used).
key: string ➡ The key to be removed from the map.
config: Map default = {recursive: false} ➡ The config map which supports the recursive option. The option recursive is false by default, and should be set to true if the input map consists of values that are also maps and, therefore, may have the key to be removed. If anything other than false or true is placed as a value for recursive, it is as if false was placed.

Output:

Map ➡ the map after removing the specified key.

Usage:

The following query will remove the c: "b" key-value pair from the map:

RETURN map.remove_key({c: "b", d: "ba"}, "c") AS map_without_c;

+----------------------------+
| map_without_c              |
+----------------------------+
| {"d": "ba"}                |
+----------------------------+

The following query will remove the c: "b", c: "h" and c: "z" key-value pairs from the main map and submap due to the recursive option set to true:

RETURN map.remove_key({c: "b", d: {e: "ba", c: "h", a: {c: "z"}}}, "c",{recursive: true}) AS removed;

+----------------------------+
| map_without_c              |
+----------------------------+
| {"d": {"e": "ba"}}         |
+----------------------------+

`remove_keys()`

The following procedure removes keys from the input map. If recursive option is set to true, it will remove keys from maps nested inside the map.

This function is equivalent to apoc.map.removeKeys.

Input:

map: Map[Any] ➡ The input map (a node or relationship may be passed; its properties are used).
keys: List[string] ➡ A list of keys that will be removed.
config: Map default = {recursive: false} ➡ A config map which supports the recursive option. The recursive option is false by default, and should be set to true if the input map consists of values that are also maps and, therefore, may have the key to be removed.

Output:

Map[Any] ➡ The resulting map.

Usage:

The following query will remove the key: 1 pair.

RETURN map.remove_keys({key: 1, key2:{key: 3, key3: 5}},["key"]) AS result;

+----------------------------------------+
| result                                 |
+----------------------------------------+
|{"key2": {"key": 3,"key3": 5}}          |
+----------------------------------------+

The following query will remove the key: 1 and key: 3 pair because te recursive options is set to true.

RETURN map.remove_keys({key: 1, key2:{key: 3, key3: 5}},["key"],{recursive: true}) AS result;

+----------------------------------------+
| result                                 |
+----------------------------------------+
|{"key2": {"key3": 5}}                   |
+----------------------------------------+

`from_pairs()`

The procedure creates a map from a list of pairs, where each pair is essentially another list of size 2. The first element in each pair must be of type string, as it will be used as a key in the resulting map.

Input:

pairs: List[List] ➡ The list of pairs.

Output:

Map ➡ A map in which the keys are the first elements in the pairs, and the corresponding values are the second elements in the pairs.

Usage:

The following query will create a map from a list:

RETURN map.from_pairs([["b", 3], ["c", "c"]]) AS map;

+----------------------------+
| map                        |
+----------------------------+
| {"b": 3, "c": "c"}         |
+----------------------------+

`merge()`

The procedure merges two maps into one. If the same key occurs twice, the later value will overwrite the previous one.

If null is provided as an argument, it will resolve to an empty map.

This function is equivalent to apoc.map.merge.

Input:

map1: mgp.Nullable[Map] ➡ The first map to merge (a node or relationship may be passed; its properties are used).
map2: mgp.Nullable[Map] ➡ The second map to merge. On a key conflict, its value takes precedence.

Output:

Map ➡ The merged input maps.

Usage:

The following query will merge maps:

RETURN map.merge({a: "b", c: "d"}, {e: "f", g: "h"}) AS merged;

+----------------------------------------+
| merged                                 |
+----------------------------------------+
| {a: "b", c: "d", e: "f", g: "h"}       |
+----------------------------------------+

`merge_list()`

Merges a list of maps into a single map. Keys are merged left to right, so when the same key appears in more than one map, the value from the last map wins. An empty list yields an empty map.

This function is equivalent to apoc.map.mergeList.

Input:

maps: List[Map] ➡ The maps to merge (each element may be a node or relationship, whose properties are used).

Output:

Map ➡ The merged map.

Usage:

The following query merges a list of maps:

RETURN map.merge_list([{a: 1}, {a: 2, b: 3}]) AS merged;

+----------------------------------------+
| merged                                 |
+----------------------------------------+
| {a: 2, b: 3}                           |
+----------------------------------------+

`flatten()`

The procedure flattens nested items in the input map.

Input:

map: Map[Any] ➡ The input map that needs to be modified (a node or relationship may be passed; its properties are used).
delimiter: string (default = ".") ➡ The delimiter used for flattening.

Output:

Map[Any] ➡ The flattened map, sorted alphabetically by keys.

Usage:

The following query will flatten the contents of the map:

RETURN map.flatten({a: {b:3, d:4}},"/") AS result;

+----------------------------------------+
| result                                 |
+----------------------------------------+
| {"a/b": 3, "a/d": 4}                   |
+----------------------------------------+

`from_lists()`

The procedure makes a map from lists of keys and corresponding values.

This function is equivalent to apoc.map.fromLists.

Input:

keys: List[string] ➡ A list of keys.
values ➡ A list of values.

Output:

Map[Any] ➡ The resulting map.

Usage:

The following query will create a map from two lists:

RETURN map.from_lists(["key","key2"],[1,2]) AS result;

+----------------------------------------+
| result                                 |
+----------------------------------------+
| {""key": 1, "key2": 2}                 |
+----------------------------------------+

`from_values()`

Returns a map from the given list of values. The list has the format: [key1, value1, key2, value2]. Keys are converted to strings; a pair whose key is null is skipped (its value is ignored).

This function is equivalent to apoc.map.fromValues.

Input:

values: List[Any] ➡ A list of values.

Output:

Map ➡ The resulting map.

Usage:

The following query will create a map from a list of values:

RETURN map.from_values(["day", "sunny", 5, 6]) AS map;

+----------------------------------------+
|        map                             |
+----------------------------------------+
| {"5": 6, "day": "sunny"}               |
+----------------------------------------+

`set_key()`

Updates the value at the position key in a map. If the key doesn’t exist, the function will insert it. A null map is treated as empty and a null key is a no-op (the map is returned unchanged).

This function is equivalent to apoc.map.setKey.

Input:

map: mgp.Nullable[Map] ➡ The map that will be modified (a node or relationship may be passed; its properties are used).
key: mgp.Nullable[string] ➡ The key to add or update; a null key leaves the map unchanged.
value: mgp.Nullable[Any] ➡ The new value of the key-value pair.

Output:

Map ➡ The modified map.

Usage:

The following query will replace the value of the key name:

RETURN map.set_key({name:"Ivan",country:"Croatia"}, "name", "Matija") AS map;

+-------------------------------------------+
|                     map                   |
+-------------------------------------------+
| {"country": "Croatia", "name": "Matija"}  |
+-------------------------------------------+

`get()`

Returns the value stored under key in the map. If the key is absent, the function returns value when it is non-null; otherwise it throws when fail is true (the default) or returns null when fail is false. An existing key always wins, even when its stored value is null.

This function is equivalent to apoc.map.get.

Input:

map: Map ➡ The map to look up (a node or relationship may be passed; its properties are used).
key: string ➡ The key to look up.
value: any (default = null) ➡ The value returned when the key is absent.
fail: boolean (default = true) ➡ When true, throws if the key is absent and value is null; when false, returns null instead.

Output:

any ➡ The value at key, the fallback value, or null.

Usage:

The following query returns the fallback value because the key is absent:

RETURN map.get({name: "Ivan"}, "country", "unknown", false) AS value;

+----------------------------------------+
| value                                  |
+----------------------------------------+
| "unknown"                              |
+----------------------------------------+

Procedures

`from_nodes()`

Returns a map of all nodes that contain the given label and property. The key of each map element will be the value of the property (if it is convertible to a string, otherwise the procedure throws ValueException).

Input:

subgraph: Graph (OPTIONAL) ➡ A specific subgraph, which is an object of type Graph returned by the project() function, on which the algorithm is run. If subgraph is not specified, the algorithm is computed on the entire graph by default.
label: string ➡ The searched label.
property: string ➡ The searched property.

Output:

result: Map ➡ The map containing all the matching nodes, their labels and properties.

Usage:

CREATE (Oppenheimer:Movie {title:'Oppenheimer', released:2023});
CREATE (Barbie:Movie {title:"Barbie", released:2023});
CREATE (Shawshank:Movie {title:'The Shawshank Redemption', released:1994});
 
CALL map.from_nodes("Movie", "title") YIELD map RETURN map;

{
   "Barbie": {
      "identity": 53,
      "labels": [
         "Movie"
      ],
      "properties": {
         "released": 2023,
         "title": "Barbie"
      }
   },
   "Oppenheimer": {
      "identity": 52,
      "labels": [
         "Movie"
      ],
      "properties": {
         "released": 2023,
         "title": "Oppenheimer"
      }
   },
   "The Shawshank Redemption": {
      "identity": 54,
      "labels": [
         "Movie"
      ],
      "properties": {
         "released": 1994,
         "title": "The Shawshank Redemption"
      }
   }
}

llm_util math