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.

TraitValue
Module typealgorithm
ImplementationC++
Graph directiondirected
Edge weightsweighted
Parallelismsequential

Procedures

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.

remove_all()

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

Input:

  • input_list: List[Any] ➡ The list from which elements need to be removed.
  • to_remove_list: List[Any] ➡ The list of elements that need to be removed.

Output:

  • removed: List[Any] ➡ The inputed 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.

CALL collections.remove_all([1, 2, 3, 4, 5], [1, 2, 3, 7]) 
YIELD removed RETURN 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]                     |
+----------------------------+

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:

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

Output:

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

Usage:

CREATE (:A {id:5});
MATCH (a:A) 
CALL collections.sum([1, 2.3, -4, a.id]) 
YIELD sum RETURN sum;
+----------------------------+
| sum                        |
+----------------------------+
| 4.3                        |
+----------------------------+

union()

Unites two lists into one, eliminating duplicates.

Input:

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

Output:

  • union: List[Any] ➡ The union of the inputed lists.

Usage:

CALL collections.union([0, 1, 2, 3], [2, 2, 3, 4, 5]) YIELD union RETURN union;
+----------------------------+
| union                      |
+----------------------------+
| [0, 1, 2, 3, 4, 5]         |
+----------------------------+

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:

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

Output:

  • sorted: List[Any] ➡ The list of sorted elements.

Usage:

CALL collections.sort([1, 4, 2.3, -5])
YIELD sorted
RETURN 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:

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

Output:

  • contains: booltrue if the element was found, false otherwise.

Usage:

CALL collections.contains_sorted([1, 2, 3.3, 4.4, 5], 2)
YIELD contains
RETURN contains;
+----------------------------+
| contains                   |
+----------------------------+
| true                       |
+----------------------------+

max()

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

Input:

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

Output:

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

Usage:

CALL collections.max([-1, -2, -3.3]) 
YIELD max 
RETURN max;
+----------------------------+
| max                        |
+----------------------------+
| -1                         |
+----------------------------+

pairs()

Creates pairs of neighbor elements within an input list.

Input:

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

Output:

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

Usage:

CALL collections.pairs([3, "s", 4.4, [1, 2]]) YIELD pairs RETURN pairs;
+---------------------------------------------------------+
| pairs                                                   |
+---------------------------------------------------------+
| [[3, "s"], ["s", 4.4], [4.4, [1, 2]], [[1, 2], null]]   |
+---------------------------------------------------------+

contains()

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

Input:

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

Output:

  • output: booleantrue if the value is present in the list, otherwise false.

Usage:

CALL collections.contains([1,2,3], "e")
YIELD output
RETURN output;
+---------------------------------------------------------+
| output                                                  |
+---------------------------------------------------------+
| false                                                   |
+---------------------------------------------------------+

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:

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

Output:

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

Usage:

CALL collections.min([1,2,3])
YIELD min
RETURN min;
+---------------------------------------------------------+
| min                                                     |
+---------------------------------------------------------+
| 1                                                       |
+---------------------------------------------------------+

unionAll()

Returns the union of two input lists, including duplicates.

Input:

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

Output:

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

Usage:

CALL collections.unionAll([1,1,2,3],[3,"a","b","c"]) 
YIELD return_list 
RETURN return_list;
+---------------------------------------------------------+
| return_list                                             |
+---------------------------------------------------------+
| [1,1,2,3,3,"a","b","c"]                                 |
+---------------------------------------------------------+

to_set()

Converts the input list to a set.

Input:

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

Output:

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

Usage:

CALL collections.to_set([1,2,1,2,3])
YIELD result
RETURN result;
+---------------------------------------------------------+
| result                                                  |
+---------------------------------------------------------+
| [3,2,1]                                                 |
+---------------------------------------------------------+

partition()

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

Input:

  • list: List[Any] ➡ The list that needs to be partitioned.
  • partition_size: integer ➡ The size of the sub-lists.

Output:

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

Usage:

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

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:

  • sum: integer ➡ The sum of listed elements.

Usage:

CALL collections.sum_longs([1.9, 1.9])
YIELD sum
RETURN 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:

  • average: double ➡ The average of listed elements.

Usage:

CALL collections.avg([5, 5, 6, 7, -5]) 
YIELD average
RETURN average;
+---------------------------------------------------------+
| average                                                 |
+---------------------------------------------------------+
| 3.6                                                     |
+---------------------------------------------------------+

contains_all()

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

Input:

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

Output:

  • contained: booleantrue if all the elements specified in the values parameter are contained in the collection list.

Usage:

CALL collections.contains_all([1, 2, 3, "pero"], [1, 1, 1, 1, 2, 3])
YIELD contained
RETURN 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:

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

Usage:

CALL collections.intersection([1, 1, 2, 3, 4, 5], [1, 1, 3, 5, 7, 9])
YIELD intersection
RETURN intersection;
+---------------------------------------------------------+
| intersection                                            |
+---------------------------------------------------------+
| [3, 5, 1]                                               |
+---------------------------------------------------------+

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:

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