collections

The collections module is a collection manipulation module that offers functions to work with lists in Cypher queries, allowing operations like filtering, sorting, and modification for efficient data handling.

Functions in the collection are called inline, while the procedure as called using the CALL subclause.

Source code

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

Functions

If a function requires elements to be comberable, Path, List and Map are uncomparable.
Only Numeric data types can be used in sum() and avg() functions, so only Int and Double data types are allowed.

Handling `NULL` values

Passing NULL as a whole list (or scalar) argument no longer raises an argument-validation error. Each function returns a defined result:

Function	Result when a list argument is `NULL`
`sum()`, `sum_longs()`, `avg()`, `min()`, `max()`, `to_set()`, `pairs()`	`null`
`union()`, `union_all()`, `disjunction()`	the other list; `null` when both are `NULL`
`remove_all()`, `subtract()`	`null` when the first list is `NULL`; the first list when the second is `NULL`
`intersection()`, `sort()`, `flatten()`, `duplicates()`	empty list `[]`
`contains()`, `contains_all()`, `contains_sorted()`	`false`
`frequencies_as_map()`	empty map `{}`
`split()`, `partition()`	no rows

NULL elements inside a list are handled per function:

min() and max() skip NULL elements; a list containing only NULL values returns null.
contains() and contains_all() never match a NULL search value (NULL = NULL is not true), so searching for NULL returns false.
split() treats a NULL delimiter as matching nothing and returns the whole list as a single part; NULL list elements are kept.
frequencies_as_map() counts NULL elements under the "NO_VALUE" key.
flatten(), pairs(), to_set(), union(), union_all(), remove_all(), intersection(), disjunction(), subtract() and duplicates() keep NULL elements as ordinary values.
sum(), sum_longs(), avg(), sort() and contains_sorted() still reject a list that contains a NULL element; contains_sorted() also rejects a NULL search value, and partition() still rejects a NULL size.

For example, a NULL argument returns the defined result instead of erroring:

RETURN collections.sum(null) AS sum, collections.sort(null) AS sorted;

+----------------------------+
| sum        | sorted        |
+----------------------------+
| null       | []            |
+----------------------------+

`sort()`

Sorts the elements of an input list if they are of the same data type. For the input list to be sorted, its elements must be comparable and of the same type.

This function is equivalent to apoc.coll.sort.

Input:

coll: List[Any] ➡ List of elements that need to be sorted.

Output:

List[Any] ➡ The list of sorted elements.

Usage:

The following query will sort elements of the list:

RETURN collections.sort([1, 4, 2.3, -5]) AS sorted;

+----------------------------+
| sorted                     |
+----------------------------+
| [-5, 1, 2.3, 4]            |
+----------------------------+

`contains_sorted()`

Verifies the presence of a certain element in a sorted list. If an unsorted list is passed, there is no guarantee that the result will be correct. For the input list to be sorted, its elements must be comparable and of the same type.

This function is equivalent to apoc.coll.containsSorted.

Input:

coll: List[Any] ➡ The target list where the element is searched for.
value: Any ➡ The element searched for.

Output:

bool ➡ true if the element was found, false otherwise.

Usage:

The following query will check if number 2 is contained within the list:

RETURN collections.contains_sorted([1, 2, 3.3, 4.4, 5], 2) AS contains;

+----------------------------+
| contains                   |
+----------------------------+
| true                       |
+----------------------------+

`union()`

Unites two lists into one, eliminating duplicates.

This function is equivalent to apoc.coll.union.

Input:

first: List[Any] ➡ The first list of elements.
second: List[Any] ➡ The second list of elements.

Output:

List[Any] ➡ The union of the two input lists.

Usage:

The following query will merge two list into one, leaving only unique elements:

RETURN collections.union([0, 1, 2, 3], [2, 2, 3, 4, 5]) AS union;

+----------------------------+
| union                      |
+----------------------------+
| [4, 3, 5, 2, 1, 0]         |
+----------------------------+

`union_all()`

Returns the union of two input lists, including duplicates.

This function is equivalent to apoc.coll.unionAll.

Input:

first: List[Any] ➡ The first list.
second: List[Any] ➡ The second list.

Output:

List[Any] ➡ The union of two lists, including duplicates.

Usage:

The following query will merge two lists into one:

RETURN collections.union_all([1,1,2,3],[3,"a","b","c"]) AS return_list;

+---------------------------------------------------------+
| return_list                                             |
+---------------------------------------------------------+
| [1,1,2,3,3,"a","b","c"]                                 |
+---------------------------------------------------------+

`remove_all()`

Removes defined elements from the input list. If a non-existent element is passed in the list, it will be ignored.

This function is equivalent to apoc.coll.removeAll.

Input:

first: List[Any] ➡ The list from which elements need to be removed.
second: List[Any] ➡ The list of elements that need to be removed.

Output:

List[Any] ➡ The input list after removing the specified elements.

Usage:

The following query will remove 1, 2, 3 and 7 from a list of numbers from 1-5.

RETURN collections.remove_all([1, 2, 3, 4, 5], [1, 2, 3, 7]) AS removed;

Only numbers 4 and 5 remain, while the number 7 was ignored as it does not exist in the input list.

+----------------------------+
| removed                    |
+----------------------------+
| [4, 5]                     |
+----------------------------+

`contains()`

Verifies the existence of an input value in an input list.

This function is equivalent to apoc.coll.contains.

Input:

coll: List[Any] ➡ The input list checked for a certain value.
value: Any ➡ The input value searched in the list.

Output:

boolean ➡ true if the value is present in the list, otherwise false.

Usage:

The following query will check if “e” is contained within the list:

RETURN collections.contains([1,2,3], "e") AS output;

+---------------------------------------------------------+
| output                                                  |
+---------------------------------------------------------+
| false                                                   |
+---------------------------------------------------------+

`contains_all()`

Checks if a list contains all the values from another list.

This function is equivalent to apoc.coll.containsAll.

Input:

coll: List[Any] ➡ The target list used for searching values.
values: List[Any] ➡ Values searched for in the target list.

Output:

boolean ➡ true if all the elements specified in the values parameter are contained in the collection list.

Usage:

The following query will check if all the unique elements from a list are contained within a target list:

RETURN collections.contains_all([1, 2, 3, "pero"], [1, 1, 1, 1, 2, 3]) AS contained;

+---------------------------------------------------------+
| contained                                               |
+---------------------------------------------------------+
| true                                                    |
+---------------------------------------------------------+

`intersection()`

Returns the unique intersection of two lists.

This function is equivalent to apoc.coll.intersection.

Input:

first: List[Any] ➡ The first list.
second: List[Any] ➡ the second list.

Output:

List[Any] ➡ The unique intersection of two lists.

Usage:

The following query will return the unique elements present in both lists:

RETURN collections.intersection([1, 1, 2, 3, 4, 5], [1, 1, 3, 5, 7, 9]) AS intersection;

+---------------------------------------------------------+
| intersection                                            |
+---------------------------------------------------------+
| [3, 5, 1]                                               |
+---------------------------------------------------------+

`disjunction()`

Returns the disjunction (symmetric difference) of two lists: the unique elements present in exactly one of the lists. The order of the result is not guaranteed.

This function is equivalent to apoc.coll.disjunction.

Input:

list1: List[Any] ➡ The first list.
list2: List[Any] ➡ The second list.

Output:

List[Any] ➡ The unique elements found in only one of the two lists.

Usage:

The following query will return the elements present in only one of the lists:

RETURN collections.disjunction([1, 2, 3, 4, 5], [3, 4, 5]) AS disjunction;

+---------------------------------------------------------+
| disjunction                                             |
+---------------------------------------------------------+
| [1, 2]                                                  |
+---------------------------------------------------------+

`subtract()`

Returns the first list as a set with all elements of the second list removed. The result is deduplicated and its order is not guaranteed.

This function is equivalent to apoc.coll.subtract.

Input:

list1: List[Any] ➡ The list to subtract from.
list2: List[Any] ➡ The list of elements to remove.

Output:

List[Any] ➡ The unique elements of the first list that are not present in the second list.

Usage:

The following query will remove the elements of the second list from the first:

RETURN collections.subtract([1, 2, 3, 4, 5, 6, 6], [3, 4, 5]) AS subtracted;

+---------------------------------------------------------+
| subtracted                                              |
+---------------------------------------------------------+
| [1, 2, 6]                                               |
+---------------------------------------------------------+

`duplicates()`

Returns the values that appear more than once in a list, each reported a single time, in the order in which the duplicate is first observed.

This function is equivalent to apoc.coll.duplicates.

Input:

coll: List[Any] ➡ The input list.

Output:

List[Any] ➡ The values that occur more than once in the input list.

Usage:

The following query will return the values that appear more than once:

RETURN collections.duplicates([1, 1, 2, 3, 3, 3]) AS duplicates;

+---------------------------------------------------------+
| duplicates                                              |
+---------------------------------------------------------+
| [1, 3]                                                  |
+---------------------------------------------------------+

`flatten()`

Returns flattened list of inputs provided.

This function is equivalent to apoc.coll.flatten.

Input:

list: List[Any] ➡ The list used to flatten.

Output:

List[Any] ➡ The list containing elements from the input list.

Usage:

The following query will flatten input list into same level:

WITH [1] as nums,
      ["text", 2.5] as mixed,
      [true, false] as bools
WITH COLLECT(nums) + [mixed] + [bools] + COLLECT(null) as input_list
RETURN collections_module.flatten(input_list) as result

+---------------------------------------------------------+
| result                                                  |
+---------------------------------------------------------+
| [1, "text", 2.5, True, False]  |
+---------------------------------------------------------+

`frequencies_as_map()`

Returns a map of frequencies of the items in the collection.

This function is equivalent to apoc.coll.frequenciesAsMap.

Input:

coll: List[Any] ➡ The collection whose item frequencies will be counted.

Output:

Map[String, Integer] ➡ A map where keys are string representations of the items, and values are their frequencies.

Usage:

The following query will count the frequency of each element in the list:

RETURN collections.frequencies_as_map([1, 1, 2, 1, 3, 4, 1, 3]) AS result;

+---------------------------------------------------------+
| result                                                  |
+---------------------------------------------------------+
| {"1": 4, "2": 1, "3": 2, "4": 1}                        |
+---------------------------------------------------------+

`pairs()`

Creates pairs of neighbor elements within an input list.

This function is equivalent to apoc.coll.pairs.

Input:

list: List[Any] ➡ The list used to create pairs.

Output:

List[Any] ➡ The list containing pairs of elements from the input list.

Usage:

The following query will create pairs of neighbor elements:

RETURN collections.pairs([3, "s", 4.4, [1, 2]]) AS pairs;

+---------------------------------------------------------+
| pairs                                                   |
+---------------------------------------------------------+
| [[3, "s"], ["s", 4.4], [4.4, [1, 2]], [[1, 2], null]]   |
+---------------------------------------------------------+

`to_set()`

Converts the input list to a set.

This function is equivalent to apoc.coll.toSet.

Input:

values: List[Any] ➡ The list that will be converted into a set.

Output:

List[Any] ➡ The set returned as an mgp::List data type.

Usage:

The following query will convert the input list into a set:

RETURN collections.to_set([1,2,1,2,3]) AS result;

+---------------------------------------------------------+
| result                                                  |
+---------------------------------------------------------+
| [3,2,1]                                                 |
+---------------------------------------------------------+

`sum()`

Calculates the sum of listed elements if they are of the same type and can be summed (the elements need to be numerics). Listing elements of different data types, or data types that are impossible to sum, will throw an exception.

This function is equivalent to apoc.coll.sum.

Input:

numbers: List[Any] ➡ The list of elements that will be summed up.

Output:

double ➡ The sum of all elements from the input list.

Usage:

The following query will sum the elements of the input list:

CREATE (:A {id:5});
MATCH (a:A) 
RETURN collections.sum([1, 2.3, -4, a.id]) AS sum;

+----------------------------+
| sum                        |
+----------------------------+
| 4.3                        |
+----------------------------+

`sum_longs()`

Calculates the sum of list elements casted to integers. The initial list elements have to be Numeric data type, or an exception is thrown.

This function is equivalent to apoc.coll.sumLongs.

Input:

numbers: List[Any] ➡ The list of numbers.

Output:

integer ➡ The sum of listed elements.

Usage:

The following query will sum the integers in the list:

RETURN collections.sum_longs([1.9, 1.9]) AS sum;

+---------------------------------------------------------+
| sum                                                     |
+---------------------------------------------------------+
| 2                                                       |
+---------------------------------------------------------+

`avg()`

Calculates the average of listed elements if they are of the same type and can be summed (the elements need to be numerics). Listing elements of different data types, or data types that are impossible to sum, will throw an exception.

This function is equivalent to apoc.coll.avg.

Input:

numbers: List[Any] ➡ The list of numbers.

Output:

double ➡ The average of listed elements.

Usage:

The following query will calculate the average of elements in the list:

RETURN collections.avg([5, 5, 6, 7, -5]) AS average;

+---------------------------------------------------------+
| average                                                 |
+---------------------------------------------------------+
| 3.6                                                     |
+---------------------------------------------------------+

`max()`

The procedure returns the element of the maximum value from the input list.

This function is equivalent to apoc.coll.max.

Input:

values: List[Any] ➡ The input list where an element of the maximum value must be found.

Output:

Any ➡ The element of the maximum value from the input list.

Usage:

Use the following procedure to get the element of the maximum value:

RETURN collections.max([-1, -2, -3.3]) AS max;

+----------------------------+
| max                        |
+----------------------------+
| -1                         |
+----------------------------+

`min()`

Finds the element of the minimum value in an input list. Listing elements of different data types, or data types that are impossible to compare, will throw an exception.

This function is equivalent to apoc.coll.min.

Input:

values: List[Any] ➡ The input list where an element of the minimum value must be found.

Output:

Any ➡ The element of the minimum value from the input list.

Usage:

Use the following query to find the element of the minimum value in the list:

RETURN collections.min([1,2,3]) AS min;

+---------------------------------------------------------+
| min                                                     |
+---------------------------------------------------------+
| 1                                                       |
+---------------------------------------------------------+

Procedures

`split()`

Splits the provided list based on a specified delimiter. Returns a series of sublists generated by breaking the original list wherever the delimiter is encountered. The delimiter itself is not included in the resulting sublists.

This procedure is equivalent to apoc.coll.split.

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.
inputList: List[Any] ➡ The input list that needs to be split.
delimiter: Any ➡ The element that determines the split point.

Output:

split: List[Any] ➡ Sublists of the original list.

Usage:

Use the following query to split the list using a 0 as a delimiter:

CALL collections.split([2, 4, "0", 0, 3.3, 9, 0, 5], 0)
YIELD split
RETURN split;

+----------------------------+
| split                      |
+----------------------------+
| [2, 4, "0"]                |
+----------------------------+
| [3.3, 9]                   |
+----------------------------+
| [5]                        |
+----------------------------+

`partition()`

Partitions the input list into sub-lists of the specified partition_size.

This procedure is equivalent to apoc.coll.partition.

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.
list: List[Any] ➡ The list that will be partitioned.
partition_size: integer ➡ The size of the sub-lists.

Output:

result: List[Any] ➡ The partitioned sub-lists.

Usage:

Use the following query to partitional the list into two elements.

CALL collections.partition([1,2,3,4,5,6],2)
YIELD result
RETURN result;

+---------------------------------------------------------+
| result                                                  |
+---------------------------------------------------------+
| [1,2]                                                   |
+---------------------------------------------------------+
| [3,4]                                                   |
+---------------------------------------------------------+
| [5,6]                                                   |
+---------------------------------------------------------+

bridges csv_utils

collections

Functions

Handling NULL values

sort()

Input:

Output:

Usage:

contains_sorted()

Input:

Output:

Usage:

union()

Input:

Output:

Usage:

union_all()

Input:

Output:

Usage:

remove_all()

Input:

Output:

Usage:

contains()

Input:

Output:

Usage:

contains_all()

Input:

Output:

Usage:

intersection()

Input:

Output:

Usage:

disjunction()

Input:

Output:

Usage:

subtract()

Input:

Output:

Usage:

duplicates()

Input:

Output:

Usage:

flatten()

Input:

Output:

Usage:

frequencies_as_map()

Input:

Output:

Usage:

pairs()

Input:

Output:

Usage:

to_set()

Input:

Output:

Usage:

sum()

Input:

Output:

Usage:

sum_longs()

Input:

Output:

Usage:

avg()

Input:

Output:

Usage:

max()

Input:

Output:

Usage:

min()

Handling `NULL` values

`sort()`

`contains_sorted()`

`union()`

`union_all()`

`remove_all()`

`contains()`

`contains_all()`

`intersection()`

`disjunction()`

`subtract()`

`duplicates()`

`flatten()`

`frequencies_as_map()`

`pairs()`

`to_set()`

`sum()`

`sum_longs()`

`avg()`

`max()`

`min()`

`split()`

`partition()`