Collection & Map Functions
Collection Functions
The list argument accepted by every coll.* function below follows the same rules as the built-in Cypher list functions (head(), tail(), reverse(), size()): a Cypher LIST, a numeric array parameter, or any Iterable/Iterator are all accepted. An argument that is none of these — a string, a number, a map — raises a client-facing Type mismatch error rather than succeeding silently or failing with a generic server error.
coll.toSet() and coll.distinct() are the same function under two names: both preserve the order of first occurrence and both recognize duplicates by object equality, so coll.toSet([1, 1.0]) and coll.distinct([1, 1.0]) both keep both elements.
coll.avg()
Returns the arithmetic mean of a list of numbers.
Syntax: coll.avg(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
A list of numbers |
Returns: Double - The average, null if the list is null, empty, or contains only nulls
Null elements are skipped rather than counted, so coll.avg([1, 2, null]) averages over the two non-null elements. A non-numeric element raises an error.
APOC Compatible: apoc.coll.avg
RETURN coll.avg([1, 2, 3, 4]) AS result
// Returns: 2.5
RETURN coll.avg([]) AS result
// Returns: null
RETURN coll.avg([1, 2, null]) AS result
// Returns: 1.5coll.distinct()
Returns a new list with duplicate values removed, preserving the order of first occurrence.
Syntax: coll.distinct(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: List - Deduplicated list, or null if input is null
APOC Compatible: apoc.coll.distinct
RETURN coll.distinct([1, 2, 2, 3, 1]) AS result
// Returns: [1, 2, 3]coll.flatten()
Flattens nested lists into a single list, with configurable depth control.
Syntax: coll.flatten(list [, depth])
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The nested list to flatten |
depth |
Integer |
(Optional) Levels of nesting to flatten. Default: 1. Use -1 for unlimited depth. |
Returns: List - Flattened list, or null if input is null
APOC Compatible: apoc.coll.flatten
RETURN coll.flatten([[1, 2], [3, 4]]) AS result
// Returns: [1, 2, 3, 4]
RETURN coll.flatten([[1, [2, 3]], [4]], -1) AS result
// Returns: [1, 2, 3, 4]
RETURN coll.flatten([[1, [2, 3]], [4]], 1) AS result
// Returns: [1, [2, 3], 4]coll.indexOf()
Returns the index of the first occurrence of a value in a list, or -1 if not found.
Syntax: coll.indexOf(list, value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The list to search |
value |
Any |
The value to find |
Returns: Integer - Zero-based index, -1 if not found, null if list or value is null
APOC Compatible: apoc.coll.indexOf
RETURN coll.indexOf(["a", "b", "c"], "b") AS result
// Returns: 1
RETURN coll.indexOf([1, 2, 3], 5) AS result
// Returns: -1coll.insert()
Returns a new list with a value inserted at the given index.
Syntax: coll.insert(list, index, value)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The original list |
index |
Integer |
Position to insert at (0-based) |
value |
Any |
Value to insert |
Returns: List - New list with value inserted, or null if input is null
APOC Compatible: apoc.coll.insert
RETURN coll.insert([1, 2, 3], 1, 99) AS result
// Returns: [1, 99, 2, 3]coll.max()
Returns the maximum value in a list using Cypher comparison semantics.
Syntax: coll.max(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: Any - Maximum value, or null if list is null or empty
APOC Compatible: apoc.coll.max
RETURN coll.max([3, 1, 4, 1, 5]) AS result
// Returns: 5coll.min()
Returns the minimum value in a list using Cypher comparison semantics.
Syntax: coll.min(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: Any - Minimum value, or null if list is null or empty
APOC Compatible: apoc.coll.min
RETURN coll.min([3, 1, 4, 1, 5]) AS result
// Returns: 1coll.pairsMin()
Returns the consecutive-element pairs of a list, dropping the trailing incomplete pair.
Syntax: coll.pairsMin(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: List - A list of two-element lists, empty for a list of fewer than two elements, or null if input is null
Unlike apoc.coll.pairs, which pads the last pair with null, this function drops it. A list of n elements therefore yields n - 1 pairs.
APOC Compatible: apoc.coll.pairsMin
RETURN coll.pairsMin([1, 2, 3]) AS result
// Returns: [[1, 2], [2, 3]]
RETURN coll.pairsMin([1]) AS result
// Returns: []Elements may be of any type, including lists, which are paired as values rather than flattened:
RETURN coll.pairsMin([[1, 2], [3, 4]]) AS result
// Returns: [[[1, 2], [3, 4]]]coll.remove()
Returns a new list with element(s) removed starting at the given index.
Syntax: coll.remove(list, index [, count])
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The original list |
index |
Integer |
Starting position (0-based) |
count |
Integer |
(Optional) Number of elements to remove. Default: 1 |
Returns: List - New list with elements removed, or null if input is null
APOC Compatible: apoc.coll.remove
RETURN coll.remove([1, 2, 3, 4, 5], 1) AS result
// Returns: [1, 3, 4, 5]
RETURN coll.remove([1, 2, 3, 4, 5], 1, 2) AS result
// Returns: [1, 4, 5]coll.sort()
Returns a sorted copy of the list using Cypher comparison semantics.
Syntax: coll.sort(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: List - Sorted list, or null if input is null
APOC Compatible: apoc.coll.sort
RETURN coll.sort([3, 1, 4, 1, 5]) AS result
// Returns: [1, 1, 3, 4, 5]coll.sum()
Returns the sum of a list of numbers.
Syntax: coll.sum(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
A list of numbers |
Returns: Double - The sum, 0.0 for an empty list, or null if input is null
Null elements are skipped. A non-numeric element raises an error.
APOC Compatible: apoc.coll.sum
RETURN coll.sum([1, 2, 3, 4]) AS result
// Returns: 10.0
RETURN coll.sum([]) AS result
// Returns: 0.0
RETURN coll.sum([1, 2, 'x']) AS result
// Error: Type mismatch: coll.sum() expects an INTEGER or a FLOAT argument but got STRINGcoll.toSet()
Returns a copy of the list with duplicates removed, preserving the order of first occurrence.
Syntax: coll.toSet(list)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list |
List |
The input list |
Returns: List - Unique list, or null if input is null
Deduplication uses object equality, so values of different numeric types are kept separately: coll.toSet([1, 1.0]) returns both elements. This matches coll.distinct(), which applies the same rule.
APOC Compatible: apoc.coll.toSet
RETURN coll.toSet([1, 2, 2, 3]) AS result
// Returns: [1, 2, 3]
RETURN coll.toSet([1, null, 1, null]) AS result
// Returns: [1, null]coll.union()
Returns the distinct union of two lists, preserving the order of first occurrence.
Syntax: coll.union(list1, list2)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list1 |
List |
The first list |
list2 |
List |
The second list |
Returns: List - Union without duplicates. A null argument contributes no elements, so coll.union(null, [1]) returns [1].
As with coll.toSet(), deduplication is by object equality: coll.union([1], [1.0]) keeps both values.
APOC Compatible: apoc.coll.union
RETURN coll.union([1, 2, 3], [2, 3, 4]) AS result
// Returns: [1, 2, 3, 4]coll.unionAll()
Returns the concatenation of two lists, preserving duplicates.
Syntax: coll.unionAll(list1, list2)
Parameters:
| Parameter | Type | Description |
|---|---|---|
list1 |
List |
The first list |
list2 |
List |
The second list |
Returns: List - All elements of both lists in order. A null argument contributes no elements.
APOC Compatible: apoc.coll.unionAll
RETURN coll.unionAll([1, 2, 3], [2, 3, 4]) AS result
// Returns: [1, 2, 3, 2, 3, 4]map.clean()
Remove null values and empty strings from a map.
Syntax: map.clean(map, [keys], [values])
Returns: Map - Cleaned map
APOC Compatible: apoc.map.clean
map.flatten()
Flatten a nested map using a delimiter.
Syntax: map.flatten(map, delimiter)
Returns: Map - Flattened map
APOC Compatible: apoc.map.flatten
RETURN map.flatten({a: {b: 1, c: 2}}, ".") AS result
// Returns: {"a.b": 1, "a.c": 2}map.fromLists()
Create a map from a list of keys and a list of values.
Syntax: map.fromLists(keys, values)
Returns: Map - New map
APOC Compatible: apoc.map.fromLists
RETURN map.fromLists(["a", "b", "c"], [1, 2, 3]) AS result
// Returns: {a: 1, b: 2, c: 3}map.fromPairs()
Create a map from a list of key-value pairs.
Syntax: map.fromPairs(pairs)
Returns: Map - New map
APOC Compatible: apoc.map.fromPairs
map.groupBy()
Group a list of maps by a key.
Syntax: map.groupBy(list, key)
Returns: Map - Map of groups
APOC Compatible: apoc.map.groupBy
RETURN map.groupBy([{type: "A", val: 1}, {type: "B", val: 2}, {type: "A", val: 3}], "type") AS result
// Returns: {A: [{type: "A", val: 1}, {type: "A", val: 3}], B: [{type: "B", val: 2}]}map.merge()
Merge two maps, with the second map’s values overriding the first.
Syntax: map.merge(map1, map2)
Returns: Map - Merged map
APOC Compatible: apoc.map.merge
RETURN map.merge({a: 1, b: 2}, {b: 3, c: 4}) AS result
// Returns: {a: 1, b: 3, c: 4}map.mergeList()
Merge a list of maps.
Syntax: map.mergeList(listOfMaps)
Returns: Map - Merged map
APOC Compatible: apoc.map.mergeList
map.removeKey()
Remove a key from a map.
Syntax: map.removeKey(map, key)
Returns: Map - Map with key removed
APOC Compatible: apoc.map.removeKey
map.removeKeys()
Remove multiple keys from a map.
Syntax: map.removeKeys(map, keys)
Returns: Map - Map with keys removed
APOC Compatible: apoc.map.removeKeys
map.setKey()
Add or update a key in a map.
Syntax: map.setKey(map, key, value)
Returns: Map - Map with key added/updated
APOC Compatible: apoc.map.setKey
RETURN map.setKey({a: 1}, "b", 2) AS result
// Returns: {a: 1, b: 2}map.sortedProperties()
Get map entries sorted by key.
Syntax: map.sortedProperties(map)
Returns: List - Sorted list of [key, value] pairs
APOC Compatible: apoc.map.sortedProperties
map.submap()
Extract a subset of keys from a map.
Syntax: map.submap(map, keys, [defaults])
Returns: Map - Submap with specified keys
APOC Compatible: apoc.map.submap