From 7c9faca7fea10ccca147eba3fd6aadcab30aa918 Mon Sep 17 00:00:00 2001 From: imilinovic Date: Tue, 21 Jul 2026 21:24:14 +0200 Subject: [PATCH 1/2] docs: document map.get and map.merge_list, and map null/coercion behavior --- .../available-algorithms/map.mdx | 97 +++++++++++++++++-- 1 file changed, 89 insertions(+), 8 deletions(-) diff --git a/pages/advanced-algorithms/available-algorithms/map.mdx b/pages/advanced-algorithms/available-algorithms/map.mdx index 320171d59..fc1e5e2e7 100644 --- a/pages/advanced-algorithms/available-algorithms/map.mdx +++ b/pages/advanced-algorithms/available-algorithms/map.mdx @@ -181,8 +181,8 @@ This function is equivalent to **apoc.map.merge**. {

Input:

} -- `first: mgp.Nullable[Map]` ➡ A map containing key-value pairs that need to be merged with another map. -- `second: mgp.Nullable[Map]` ➡ The second map containing key-value pairs that need to be merged with the key-values from the first map. +- `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:

} @@ -204,6 +204,40 @@ RETURN map.merge({a: "b", c: "d"}, {e: "f", g: "h"}) AS merged; +----------------------------------------+ ``` +### `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: + +```cypher +RETURN map.merge_list([{a: 1}, {a: 2, b: 3}]) AS merged; +``` + +```plaintext ++----------------------------------------+ +| merged | ++----------------------------------------+ +| {a: 2, b: 3} | ++----------------------------------------+ +``` + ### `flatten()` The procedure flattens nested items in the input map. @@ -270,8 +304,12 @@ RETURN map.from_lists(["key","key2"],[1,2]) AS result; ### `from_values()` Returns a map from the given list of values. The list has the format: `[key1, -value1, key2, value2]`. If the key is not convertible to a string, the function -throws `ValueException`. +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:

} @@ -300,13 +338,18 @@ RETURN map.from_values(["day", "sunny", 5, 6]) AS map; ### `set_key()` Updates the value at the position `key` in a map. If the key doesn't exist, -the function will insert it. +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: Map` ➡ The map that will be modified. -- `key: string` ➡ The key of a certain key-value pair that needs to have a new value. -- `value: any` ➡ The new value of a certain key-value pair. +- `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: any` ➡ The new value of the key-value pair. {

Output:

} @@ -328,6 +371,44 @@ RETURN map.set_key({name:"Ivan",country:"Croatia"}, "name", "Matija") AS map; +-------------------------------------------+ ``` +### `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: + +```cypher +RETURN map.get({name: "Ivan"}, "country", "unknown", false) AS value; +``` + +```plaintext ++----------------------------------------+ +| value | ++----------------------------------------+ +| "unknown" | ++----------------------------------------+ +``` + ## Procedures ### `from_nodes()` From e334b62868f01421b3e1e3b7ec3865137d982e50 Mon Sep 17 00:00:00 2001 From: imilinovic Date: Fri, 24 Jul 2026 09:20:37 +0200 Subject: [PATCH 2/2] docs: note node/relationship coercion for map.remove_key, remove_keys, flatten --- pages/advanced-algorithms/available-algorithms/map.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/advanced-algorithms/available-algorithms/map.mdx b/pages/advanced-algorithms/available-algorithms/map.mdx index fc1e5e2e7..d47080884 100644 --- a/pages/advanced-algorithms/available-algorithms/map.mdx +++ b/pages/advanced-algorithms/available-algorithms/map.mdx @@ -40,7 +40,7 @@ from any inner maps that are part of the input map. {

Input:

} -- `map: Map` ➡ The map from which the key will be removed. +- `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 @@ -94,7 +94,7 @@ This function is equivalent to **apoc.map.removeKeys**. {

Input:

} -- `map: Map[Any]` ➡ The input map. +- `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 @@ -244,7 +244,7 @@ The procedure flattens nested items in the input map. {

Input:

} -- `map: Map[Any]` ➡ The input map that needs to be modified. +- `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:

}