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.

`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.

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.

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.

Input:

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

Output:

List[Any] ➡ The union of the inputed 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.

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.

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 existance of an input value in an input list.

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.

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.

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]                                               |
+---------------------------------------------------------+

`pairs()`

Creates pairs of neighbor elements within an input list.

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.

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.

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.

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.

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.

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.

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 minimu 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.

Input:

inputList: List[Any] ➡ The input list that needs to be split.
delimiter: Any ➡ The element that determines the split point.

Output:

splitted: 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 splitted
RETURN splitted;

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

`partition()`

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

Input:

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]                                                   |
+---------------------------------------------------------+