9.3. Collection Functions

This section describes functions and procedures for working with collections and lists.

APOC has a wide variety of Collection and List functions.

apoc.coll.sum([0.5,1,2.3])

sum of all values in a list

apoc.coll.avg([0.5,1,2.3])

avg of all values in a list

apoc.coll.min([0.5,1,2.3])

minimum of all values in a list

apoc.coll.max([0.5,1,2.3])

maximum of all values in a list

apoc.coll.sumLongs([1,3,3])

sums all numeric values in a list

apoc.coll.partition(list,batchSize)

partitions a list into sublists of batchSize

apoc.coll.zip([list1],[list2])

all values in a list

apoc.coll.pairs([1,2,3]) YIELD value

[1,2],[2,3],[3,null]

apoc.coll.pairsMin([1,2,3]) YIELD value

[1,2],[2,3]

apoc.coll.toSet([list])

returns a unique list backed by a set

apoc.coll.sort(coll)

sort on Collections

apoc.coll.sortNodes([nodes], 'name')

sort nodes by property, ascending sorting by adding ^ in front of the sorting field

apoc.coll.sortMaps([maps], 'key')

sort maps by map key, ascending sorting by adding ^ in front of the sorting field

apoc.coll.reverse(coll)

returns the reversed list

apoc.coll.contains(coll, value)

returns true if collection contains the value

apoc.coll.containsAll(coll, values)

optimized contains-all operation (using a HashSet) returns true or false

apoc.coll.containsSorted(coll, value)

optimized contains on a sorted list operation (Collections.binarySearch) (returns true or false)

apoc.coll.containsAllSorted(coll, value)

optimized contains-all on a sorted list operation (Collections.binarySearch) (returns true or false)

apoc.coll.isEqualCollection(coll, values)

return true if two collections contain the same elements with the same cardinality in any order (using a HashMap)

apoc.coll.union(first, second)

creates the distinct union of the 2 lists

apoc.coll.unionAll(first, second)

creates the full union with duplicates of the two lists

apoc.coll.subtract(first, second)

returns unique set of first list with all elements of second list removed

apoc.coll.removeAll(first, second)

returns first list with all elements of second list removed

apoc.coll.intersection(first, second)

returns the unique intersection of the two lists

apoc.coll.disjunction(first, second)

returns the disjunct set of the two lists

apoc.coll.split(list,value)

splits collection on given values rows of lists, value itself will not be part of resulting lists

apoc.coll.indexOf(coll, value)

position of value in the list

apoc.coll.shuffle(coll)

returns the shuffled list

apoc.coll.randomItem(coll)

returns a random item from the list

apoc.coll.randomItems(coll, itemCount, allowRepick: false)

returns a list of itemCount random items from the list, optionally allowing picked elements to be picked again

apoc.coll.containsDuplicates(coll)

returns true if a collection contains duplicate elements

apoc.coll.duplicates(coll)

returns a list of duplicate items in the collection

apoc.coll.duplicatesWithCount(coll)

returns a list of duplicate items in the collection and their count, keyed by item and count (e.g., [{item: xyz, count:2}, {item:zyx, count:5}])

apoc.coll.occurrences(coll, item)

returns the count of the given item in the collection

apoc.coll.frequencies(coll)

returns a list of frequencies of the items in the collection, keyed by item and count (e.g., [{item: xyz, count:2}, {item:zyx, count:5}, {item:abc, count:1}])

apoc.coll.frequenciesAsMap(coll)

return a map of frequencies of the items in the collection, keyed by item and count (e.g., {1: 2, 3: 2})

apoc.coll.sortMulti

sort list of maps by several sort fields (ascending with ^ prefix) and optionally applies limit and skip

apoc.coll.flatten

flattens a nested list

apoc.coll.combinations(coll, minSelect, maxSelect:minSelect)

Returns collection of all combinations of list elements of selection size between minSelect and maxSelect (default:minSelect), inclusive

CALL apoc.coll.elements(list,limit,offset) yield _1,_2,..,_10,_1s,_2i,_3f,_4m,_5l,_6n,_7r,_8p

deconstruct subset of mixed list into identifiers of the correct type

apoc.coll.set(coll, index, value)

set index to value

apoc.coll.insert(coll, index, value)

insert value at index

apoc.coll.insertAll(coll, index, values)

insert values at index

apoc.coll.remove(coll, index, [length=1])

remove range of values from index to length

apoc.coll.different(values)

returns true if value are different

apoc.coll.fill(item, count)

returns a list with the given count of items

apoc.coll.sortText(coll, conf)

sort on string based collections

The following computes the sum of values in a list: 

RETURN apoc.coll.sum([1,2,3,4,5]) AS output

Table 9.25. Results
Output

15.0

The following computes the average of values in a list: 

RETURN apoc.coll.avg([1,2,3,4,5]) AS output

Table 9.26. Results
Output

3.0

The following computes the minimum of values in a list: 

RETURN apoc.coll.min([1,2,3,4,5]) AS output

Table 9.27. Results
Output

1

The following computes the maximum of values in a list: 

RETURN apoc.coll.max([1,2,3,4,5]) AS output

Table 9.28. Results
Output

5

The following computes the sum of numeric values in a list: 

RETURN apoc.coll.sumLongs([1,2,3,4,5]) AS output

Table 9.29. Results
Output

15

The following partitions a list into sublists of size 2

CALL apoc.coll.partition([1,2,3,4,5], 2)

Table 9.30. Results
Value

[1, 2]

[3, 4]

[5]

The following combines two lists, element for element, into a list of lists: 

RETURN apoc.coll.zip([1,2,3], ["a", "b", "c"]) as output

Table 9.31. Results
Output

[[1, "a"], [2, "b"], [3, "c"]]

The following creates a list of lists of adjacent elements in a list: 

RETURN apoc.coll.pairs([1,2,3,4,5]) AS output

Table 9.32. Results
Output

[[1, 2], [2, 3], [3, 4], [4, 5], [5, null]]

The following creates a list of lists of adjacent elements in a list, skipping the last item: 

RETURN apoc.coll.pairsMin([1,2,3,4,5]) AS output

Table 9.33. Results
Output

[[1, 2], [2, 3], [3, 4], [4, 5]]

The following converts a list to a set: 

RETURN apoc.coll.toSet([1,1,2,1,3,4,1]) AS output

Table 9.34. Results
Output

[1, 2, 3, 4]

The following sorts a collection: 

RETURN apoc.coll.sort([5,4,2,3,1]) AS output

Table 9.35. Results
Output

[1, 2, 3, 4, 5]

The following sorts a list of maps in reverse alphabetical order by the key name

RETURN apoc.coll.sortMaps([
    {name: "Lionel Messi"},
    {name: "Cristiano Ronaldo"},
    {name: "Wayne Rooney"}
], "name") AS output

Table 9.36. Results
Output
[
    {
      "name": "Wayne Rooney"
    }
    ,
    {
      "name": "Lionel Messi"
    }
    ,
    {
      "name": "Cristiano Ronaldo"
    }
]

The following sorts a list of maps in alphabetical order by the key name

RETURN apoc.coll.sortMaps([
    {name: "Lionel Messi"},
    {name: "Cristiano Ronaldo"},
    {name: "Wayne Rooney"}
], "name^") AS output

Table 9.37. Results
Output
[
    {
      "name": "Cristiano Ronaldo"
    }
    ,
    {
      "name": "Lionel Messi"
    }
    ,
    {
      "name": "Wayne Rooney"
    }
]

The following reverses a collection: 

RETURN apoc.coll.reverse([5,4,3,2,1]) AS output

Table 9.38. Results
Output

[1, 2, 3, 4, 5]

The following checks if a collection contains a value: 

RETURN apoc.coll.contains([1,2,3,4,5], 4) AS output

Table 9.39. Results
Output

true

The following checks if a collection contains all the values from another collection: 

RETURN apoc.coll.contains([1,2,3,4,5], [3,7]) AS output

Table 9.40. Results
Output

false

The following creates a distinct union of two lists: 

RETURN apoc.coll.union([1,2,3,4,5], [3,4,5,6,7]) AS output

Table 9.41. Results
Output

[1, 2, 3, 4, 5, 6, 7]

The following creates the full union of two lists: 

RETURN apoc.coll.unionAll([1,2,3,4,5], [3,4,5,6,7]) AS output

Table 9.42. Results
Output

[1, 2, 3, 4, 5, 3, 4, 5, 6, 7]

The following returns unique set of first list with all elements of second list removed: 

RETURN apoc.coll.subtract([1,2,3,4,5,6,6], [3,4,5]) AS output

Table 9.43. Results
Output

[1, 2, 6]

The following returns unique set of first list with all elements of second list removed: 

RETURN apoc.coll.subtract([1,2,3,4,5,6,6], [3,4,5]) AS output

Table 9.44. Results
Output

[1, 2]

The following returns first list with all elements of second list removed: 

RETURN apoc.coll.removeAll([1,2,3,4,5,6,6], [3,4,5]) AS output

Table 9.45. Results
Output

[1, 2, 6, 6]

The following returns the unique intersection of the two lists: 

RETURN apoc.coll.intersection([1,2,3,4,5], [3,4,5]) AS output

Table 9.46. Results
Output

[3, 4, 5]

The following returns the unique disjunction of two lists: 

RETURN apoc.coll.disjunction([1,2,3,4,5], [3,4,5]) AS output

Table 9.47. Results
Output

[1, 2]

The following splits a collection on the value .

CALL apoc.coll.split(["Hello", "World", ".", "How", "are", "you", "?"], ".")

Table 9.48. Results
Value

["Hello", "World"]

["How", "are", "you", "?"]

The following returns the index of the value 3 in the list: 

RETURN apoc.coll.indexOf([1,3,5,7,9], 3) AS output

Table 9.49. Results
Output

1

The following shuffles a list: 

RETURN apoc.coll.shuffle([1,3,5,7,9]) AS output

Table 9.50. Results
Output

[7, 5, 9, 3, 1]

The following returns a random value from a list: 

RETURN apoc.coll.randomItem([1,3,5,7,9]) AS output

Table 9.51. Results
Output

7

The following returns 2 random values from a list: 

RETURN apoc.coll.randomItems([1,3,5,7,9], 2) AS output

Table 9.52. Results
Output

[5, 3]

The following indicates whether a list contains duplicate values: 

RETURN apoc.coll.containsDuplicates([1,3,5,7,9,9]) AS output

Table 9.53. Results
Output

true

The following returns a list of duplicates in a list: 

RETURN apoc.coll.duplicates([1,3,5,7,9,9]) AS output

Table 9.54. Results
Output

[9]

The following returns duplicates in a list of maps containing an item and its count: 

RETURN apoc.coll.duplicatesWithCount([1,3,5,7,9,9]) AS output

Table 9.55. Results
Output
[
    {
      "count": 2,
      "item": 9
    }
]

The following returns the number of occurrences of the value 9 in a list: 

RETURN apoc.coll.occurrences([1,3,5,7,9,9], 9) AS output

Table 9.56. Results
Output

2

The following returns a list of maps containing each item and their frequency in a collection: 

RETURN apoc.coll.frequencies([1,3,5,7,9,9]) AS output

Table 9.57. Results
Output
[
    {
      "count": 1,
      "item": 1
    }
    ,
    {
      "count": 1,
      "item": 3
    }
    ,
    {
      "count": 1,
      "item": 5
    }
    ,
    {
      "count": 1,
      "item": 7
    }
    ,
    {
      "count": 2,
      "item": 9
    }
]

The following returns a map containing each item and their frequency in a collection: 

RETURN apoc.coll.frequenciesAsMap([1,3,5,7,9,9]) AS output

Table 9.58. Results
Output
{
  "1": 1,
  "3": 1,
  "5": 1,
  "7": 1,
  "9": 2
}

The following flattens a collection of collections: 

RETURN apoc.coll.flatten([1,2,3,[4,5,6]]) AS output

Table 9.59. Results
Output

[1, 2, 3, 4, 5, 6]

The following returns a collection of all combinations of list elements of selection size between 3 and 4 elements: 

RETURN apoc.coll.combinations([1,3,5,7,9], 3, 4) AS output

Table 9.60. Results
Output

[[1, 3, 5], [1, 3, 7], [1, 5, 7], [3, 5, 7], [1, 3, 9], [1, 5, 9], [3, 5, 9], [1, 7, 9], [3, 7, 9], [5, 7, 9], [1, 3, 5, 7], [1, 3, 5, 9], [1, 3, 7, 9], [1, 5, 7, 9], [3, 5, 7, 9]]

The following replaces the item at index 4 with the value 11

RETURN apoc.coll.set([1,3,5,7,9], 4, 11) AS output

Table 9.61. Results
Output

[1, 3, 5, 7, 11]

The following inserts the value 11 at index 3 in the list: 

RETURN apoc.coll.insert([1,3,5,7,9], 3, 11) AS output

Table 9.62. Results
Output

[1, 3, 5, 11, 7, 9]

The following removes 2 values, starting from index 1

RETURN apoc.coll.remove([1,3,5,7,9], 1, 2) AS output

Table 9.63. Results
Output

[1, 7, 9]

The following indicates whether all values in a collection are different: 

RETURN apoc.coll.different([1,3,5,7,9]) AS output

Table 9.64. Results
Output

true

The following sort a list of strings: 

// n.b. if no locale is provided it takes the default of the machine where neo4j is running on
RETURN apoc.coll.sortText(['Єльська', 'Гусак'], {locale: 'ru'}) as Output

Table 9.65. Results
Output

Гусак

Єльська