## 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

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