List functions

List functions return lists of different data entities.

For more information about working with LIST values, see:

Example graph

The following graph is used for the examples below:

To recreate the graph, run the following query against an empty Neo4j database:

CREATE
  (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}),
  (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}),
  (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}),
  (daniel:Administrator {name: 'Daniel', age: 54, eyes: 'Brown'}),
  (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:KNOWS]->(charlie),
  (bob)-[:KNOWS]->(daniel),
  (charlie)-[:KNOWS]->(daniel),
  (bob)-[:MARRIED]->(eskil)

coll.distinct()

Details
Syntax	`coll.distinct(list)`
Description	Returns the given list with all duplicate values removed.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to be deduplicated.
Returns	`LIST<ANY>`

Considerations
`coll.distinct(null)` returns `null`.
The order of the first occurrences of the distinct values is preserved.

Example 1. coll.distinct()

Deduplicate a list of integer values

RETURN coll.distinct([1, 3, 2, 4, 2, 3, 1])

A LIST<ANY> containing only unique values is returned.

Result
coll.distinct([1, 3, 2, 4, 2, 3, 1])
`[1, 3, 2, 4]`
Rows: 1

Deduplicate a list of mixed values, including null

RETURN coll.distinct([1, true, true, null, 'a', false, true, 1, null])

A LIST<ANY> containing only unique values is returned.

Result
coll.distinct([1, true, true, null, 'a', false, true, 1, null])
`[1, true, null, 'a', false]`
Rows: 1

coll.flatten()

Details
Syntax	`coll.flatten(list [, depth])`
Description	Returns a list flattened to the given nesting depth.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A nested list to be flattened.
	`depth`	`INTEGER`	The maximum depth to flatten to (default value: 1).
Returns	`LIST<ANY>`

Considerations
Preserves the original order of non-list items.
If `depth` is 0, the input list is returned unchanged.
`depth` must be a non-negative integer.
`coll.flatten(null)` returns `null`.
`coll.flatten(list, null)` returns `null`.
`coll.flatten(null, depth)` returns `null`.
`coll.flatten(null, null)` returns `null`.

Example 2. coll.flatten()

Flatten a list containing nesting to level 2

RETURN coll.flatten(['a', ['b', ['c']]], 2)

A LIST<ANY> with any inner lists up to a nesting depth of 2 flattened.

Result
coll.flatten(['a', ['b', ['c']]], 2)
`['a', 'b', 'c']`
Rows: 1

Flatten a list to default of depth 1

RETURN coll.flatten(['a', ['b', ['c']]])

A LIST<ANY> with any inner lists up to a nesting depth of 1 (default depth) flattened.

Result
coll.flatten(['a', ['b', ['c']]])
`['a', 'b', ['c']]`
Rows: 1

coll.indexOf()

Details
Syntax	`coll.indexOf(list, value)`
Description	Returns the index of the first match of a value in the given list or -1 if the value is not present.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to be searched.
	`value`	`ANY`	A value to search for.
Returns	`INTEGER`

Considerations
Indexing is 0-based.
Returns -1 if the value is not present in the list.
`coll.indexOf(null, null)` returns `null`.
`coll.indexOf(null, value)` returns `null`.
`coll.indexOf(list, null)` returns `null`.

Example 3. coll.indexOf()

Find the first index of a given value

RETURN coll.indexOf(['a', 'b', 'c', 'c'], 'c')

An INTEGER representing the index of the item in the list.

Result
coll.indexOf(['a', 'b', 'c', 'c'], 'c')
`2`
Rows: 1

Search for a value not present in the given list

RETURN coll.indexOf([1, 'b', false], 4.3)

The INTEGER -1 representing that the value is not found.

Result
coll.indexOf([1, 'b', false], 4.3)
`-1`
Rows: 1

coll.insert()

Details
Syntax	`coll.insert(list, index, value)`
Description	Returns a list with the given value inserted at the given index.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to add to.
	`index`	`INTEGER`	The index to add the given value at.
	`value`	`ANY`	The value to add into the list.
Returns	`LIST<ANY>`

Considerations
Indexing is 0-based.
`coll.insert(null, null, value)` returns `null`.
`coll.insert(list, null, value)` returns `null`.
`coll.insert(null, 1, value)` returns `null`.
If the given `index` is negative or larger than the size of the given list, an error is returned.

Example 4. coll.insert()

Query

RETURN coll.insert([true, 'a', 1, 5.4], 1, false)

The original list with a new value inserted at the given index, shifting all the values following by 1.

Result
coll.insert([true, 'a', 1, 5.4], 1, false)
`[true, false, 'a', 1, 5.4]`
Rows: 1

coll.max()

Details
Syntax	`coll.max(list)`
Description	Returns the largest value present in the given list.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to be searched.
Returns	`ANY`

Considerations
`coll.max(null)` returns `null`.
`coll.max([])` returns `null`.
The maximum is determined using Cypher^®'s standard value ordering; see Equality, ordering, and comparison of value types.

Example 5. coll.max()

Query

RETURN coll.max([true, 'a', 1, 5.4])

The maximum value found in the given list based on Cypher’s ordering.

Result
coll.max([true, 'a', 1, 5.4])
`5.4`
Rows: 1

coll.min()

Details
Syntax	`coll.min(list)`
Description	Returns the smallest value present in the given list.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to be searched.
Returns	`ANY`

Considerations
`coll.min(null)` returns `null`.
`coll.min([])` returns `null`.
The minimum is determined using Cypher’s standard value ordering; see Equality, ordering, and comparison of value types.

Example 6. coll.min()

Query

RETURN coll.min([true, 'a', 1, 5.4])

The minimum value found in the given list based on Cypher’s ordering.

Result
coll.min([true, 'a', 1, 5.4])
`true`
Rows: 1

coll.remove()

Details
Syntax	`coll.remove(list, index)`
Description	Returns a list with the value at the given index removed.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to remove a value from.
	`index`	`INTEGER`	The index of the value to be removed.
Returns	`LIST<ANY>`

Considerations
Indexing is 0-based.
`coll.remove(null, null)` returns `null`.
`coll.remove(null, index)` returns `null`.
`coll.remove(list, null)` returns `null`.
If the given `index` is negative or larger than the size of the given list, an error is returned.

Example 7. coll.remove()

Query

RETURN coll.remove([true, 'a', 1, 5.4], 1)

The original list with the value at the given index removed and all values following shifted by 1.

Result
coll.remove([true, 'a', 1, 5.4], 1)
`[true, 1, 5.4]`
Rows: 1

coll.sort()

Details
Syntax	`coll.sort(list)`
Description	Returns a sorted list.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list to be sorted.
Returns	`LIST<ANY>`

Considerations
Sorting follows Cypher’s standard value ordering; see Equality, ordering, and comparison of value types.
`coll.sort(null)` returns `null`.

Example 8. coll.sort()

Query

RETURN coll.sort([true, 'a', 1, 2])

The list sorted using Cypher’s ordering in ascending order.

Result
coll.sort([true, 'a', 1, 2])
`['a', true, 1, 2]`
Rows: 1

keys()

Details
Syntax	`keys(input)`
Description	Returns a `LIST<STRING>` containing the `STRING` representations for all the property names of a `NODE`, `RELATIONSHIP` or `MAP`.
Arguments	Name	Type	Description
	`input`	`NODE \| RELATIONSHIP \| MAP`	A node or relationship from which the names of all properties will be returned.
Returns	`LIST<STRING>`

Considerations
`keys(null)` returns `null`.

Example 9. keys()

Query

MATCH (a) WHERE a.name = 'Alice'
RETURN keys(a)

A LIST<STRING> containing the names of all the properties on the node bound to a is returned.

Result
keys(a)
`["eyes", "name", "age"]`
Rows: 1

labels()

Details
Syntax	`labels(input)`
Description	Returns a `LIST<STRING>` containing the `STRING` representations for all the labels of a `NODE`.
Arguments	Name	Type	Description
	`input`	`NODE`	A node whose labels will be returned.
Returns	`LIST<STRING>`

Considerations
`labels(null)` returns `null`.
The order of the returned labels is not guaranteed when using the `labels()` function.

Example 10. labels()

Query

MATCH (a) WHERE a.name = 'Alice'
RETURN labels(a)

A LIST<STRING> containing all the labels of the node bound to a is returned.

Result
labels(a)
`["Developer"]`
Rows: 1

nodes()

Details
Syntax	`nodes(input)`
Description	Returns a `LIST<NODE>` containing all the `NODE` values in a `PATH`.
Arguments	Name	Type	Description
	`input`	`PATH`	A path whose nodes will be returned.
Returns	`LIST<NODE>`

Considerations
The `NODE` values in the returned `LIST` are guaranteed to be in the exact order they appear along the path traversal, from the starting node to the end node.
`nodes(null)` returns `null`.

Example 11. nodes()

Query

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice' AND c.name = 'Eskil'
RETURN nodes(p)

A LIST<NODE> containing all the nodes in the path p is returned.

Result
nodes(p)
`[(:Developer {name: "Alice", eyes: "Brown", age: 38}), (:Administrator {name: "Bob", eyes: "Blue", age: 25}), (:Designer {name: "Eskil", likedColors: ["Pink", "Yellow", "Black"], eyes: "blue", age: 41})]`
Rows: 1

range()

Details
Syntax	`range(start, end [, step])`
Description	Returns a `LIST<INTEGER>` comprising all `INTEGER` values within a specified range created with step length, optionally specifying a step length.
Arguments	Name	Type	Description
	`start`	`INTEGER`	The start value of the range.
	`end`	`INTEGER`	The end value of the range.
	`step`	`INTEGER`	The size of the increment (default value: 1).
Returns	`LIST<INTEGER>`

Considerations
To create ranges with decreasing `INTEGER` values, use a negative value `step`.
The range is inclusive for non-empty ranges, and the arithmetic progression will therefore always contain `start` and — depending on the values of `start`, `step` and `end` — `end`. The only exception where the range does not contain `start` are empty ranges.
An empty range will be returned if the value `step` is negative and `start - end` is positive, or vice versa, e.g. `range(0, 5, -1)`.

Example 12. range()

Query

RETURN range(0, 10), range(2, 18, 3), range(0, 5, -1)

Three lists of numbers in the given ranges are returned.

Result
range(0, 10)	range(2, 18, 3)	range(0, 5, -1)
`[0,1,2,3,4,5,6,7,8,9,10]`	`[2,5,8,11,14,17]`	`[]`
Rows: 1

reduce()

Details
Syntax	`reduce(accumulator = initial, variable IN list \| expression)`
Description	Runs an expression against individual elements of a `LIST<ANY>`, storing the result of the expression in an accumulator.
Arguments	Name	Type	Description
	`accumulator`	`ANY`	A variable that holds the result as the `list` is iterated. Starts with an `initial` value.
	`initial`	`ANY`	The starting value of the `accumulator`.
	`variable`	`ANY`	A variable that represents each element in the `list` during iteration.
	`list`	`LIST<ANY>`	The `list` that is being iterated over.
	`expression`	`ANY`	An expression that updates the `accumulator` with each iteration.
Returns	`ANY`

Considerations
`reduce()` differs from most Cypher functions because it iterates over a list, incrementally updating an accumulator with each element based on an expression, rather than returning a result from a single evaluation. As such, Cypher’s `reduce()` is analogous to the `fold` or `reduce` methods in functional languages such as Lisp and Scala.

Example 13. reduce()

Query

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice' AND b.name = 'Bob' AND c.name = 'Daniel'
RETURN reduce(totalAge = 0, n IN nodes(p) | totalAge + n.age) AS reduction

The age property of all NODE values in the PATH are summed and returned as a single value.

Result
reduction
`117`
Rows: 1

relationships()

Details
Syntax	`relationships(input)`
Description	Returns a `LIST<RELATIONSHIP>` containing all the `RELATIONSHIP` values in a `PATH`.
Arguments	Name	Type	Description
	`input`	`PATH`	The path from which all relationships will be returned.
Returns	`LIST<RELATIONSHIP>`

Considerations
`relationships(null)` returns `null`.

Example 14. relationships()

Query

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice' AND c.name = 'Eskil'
RETURN relationships(p)

A LIST<RELATIONSHIP> containing all the RELATIONSHIP values in the PATH p is returned.

Result
relationships(p)
`[[:KNOWS], [:MARRIED]]`
Rows: 1

reverse()

Details
Syntax	`reverse(input)`
Description	Returns a `STRING` or `LIST<ANY>` in which the order of all characters or elements in the given `STRING` or `LIST<ANY>` have been reversed.
Arguments	Name	Type	Description
	`input`	`STRING \| LIST<ANY>`	The string or list to be reversed.
Returns	`STRING \| LIST<ANY>`

Considerations
Any `null` element in `original` is preserved.
See also String functions → `reverse()`.

Example 15. reverse()

Query

WITH [4923,'abc',521, null, 487] AS ids
RETURN reverse(ids)

Result
reverse(ids)
`[487,<null>,521,"abc",4923]`
Rows: 1

tail()

Details
Syntax	`tail(input)`
Description	Returns all but the first element in a `LIST<ANY>`.
Arguments	Name	Type	Description
	`input`	`LIST<ANY>`	A list from which all but the first element will be returned.
Returns	`LIST<ANY>`

Example 16. tail()

Query

MATCH (a) WHERE a.name = 'Eskil'
RETURN a.likedColors, tail(a.likedColors)

The property named likedColors and a LIST<ANY> comprising all but the first element of the likedColors property are returned.

Result
a.likedColors	tail(a.likedColors)
`["Pink", "Yellow", "Black"]`	`["Yellow", "Black"]`
Rows: 1

toBooleanList()

Details
Syntax	`toBooleanList(input)`
Description	Converts a `LIST<ANY>` of values to a `LIST<BOOLEAN>` values. If any values are not convertible to `BOOLEAN` they will be null in the `LIST<BOOLEAN>` returned.
Arguments	Name	Type	Description
	`input`	`LIST<ANY>`	A list of values to be converted into a list of booleans.
Returns	`LIST<BOOLEAN>`

Considerations
Any `null` element in `input` is preserved.
Any `BOOLEAN` value in `input` is preserved.
If the `input` is `null`, `null` will be returned.
If the `input` is not a `LIST<ANY>`, an error will be returned.
The conversion for each value in `input` is done according to the `toBooleanOrNull()` function.

Example 17. toBooleanList()

Query

RETURN toBooleanList(null) as noList,
toBooleanList([null, null]) as nullsInList,
toBooleanList(['a string', true, 'false', null, ['A','B']]) as mixedList

Result
noList	nullsInList	mixedList
`<null>`	`[<null>,<null>]`	`[<null>,true,false,<null>,<null>]`
Rows: 1

toFloatList()

Details
Syntax	`toFloatList(input)`
Description	Converts a `LIST<ANY>` or a `VECTOR` to a `LIST<FLOAT>` values. If any values are not convertible to `FLOAT` they will be null in the `LIST<FLOAT>` returned.
Arguments	Name	Type	Description
	`input`	`VECTOR` \| `LIST<ANY>`	A list of values or a vector value to be converted into a list of floats.
Returns	`LIST<FLOAT>`

Considerations
Any `null` element in `input` is preserved.
Any `FLOAT` value in `input` is preserved.
If the `input` is `null`, `null` will be returned.
If the `input` is not a `VECTOR` or `LIST<ANY>`, an error will be returned.
`input` accepts `VECTOR` values as of Neo4j 2025.xx
The conversion for each value in `input` is done according to the `toFloatOrNull()` function.

Example 18. toFloatList()

Query

RETURN toFloatList(null) as noList,
toFloatList([null, null]) as nullsInList,
toFloatList(['a string', 2.5, '3.14159', null, ['A','B']]) as mixedList

Result
noList	nullsInList	mixedList
`<null>`	`[<null>,<null>]`	`[<null>,2.5,3.14159,<null>,<null>]`
Rows: 1

toIntegerList()

Details
Syntax	`toIntegerList(input)`
Description	Converts a `LIST<ANY>` or a `VECTOR` to a `LIST<INTEGER>` values. If any values are not convertible to `INTEGER` they will be null in the `LIST<INTEGER>` returned.
Arguments	Name	Type	Description
	`input`	`VECTOR` \| `LIST<ANY>`	A list of values or a vector value to be converted into a list of integers.
Returns	`LIST<INTEGER>`

Considerations
Any `null` element in `input` is preserved.
Any `INTEGER` value in `input` is preserved.
If the `input` is `null`, `null` will be returned.
If the `input` is not a `VECTOR` or a `LIST<ANY>`, an error will be returned.
`input` accepts `VECTOR` values as of Neo4j 2025.10
The conversion for each value in `list` is done according to the `toIntegerOrNull()` function.

Example 19. toIntegerList()

Query

RETURN toIntegerList(null) as noList,
toIntegerList([null, null]) as nullsInList,
toIntegerList(['a string', 2, '5', null, ['A','B']]) as mixedList

Result
noList	nullsInList	mixedList
`<null>`	`[<null>,<null>]`	`[<null>,2,5,<null>,<null>]`
Rows: 1

toStringList()

Details
Syntax	`toStringList(input)`
Description	Converts a `LIST<ANY>` to a `LIST<STRING>` values. If any values are not convertible to `STRING` they will be null in the `LIST<STRING>` returned.
Arguments	Name	Type	Description
	`input`	`LIST<ANY>`	A list of values to be converted into a list of strings.
Returns	`LIST<STRING>`

Considerations
Any `null` element in `input` is preserved.
Any `STRING` value in `input` is preserved.
If the `input` is `null`, `null` will be returned.
If the `input` is not a `LIST<ANY>`, an error will be returned.
The conversion for each value in `input` is done according to the `toStringOrNull()` function.

Example 20. toStringList()

Query

RETURN toStringList(null) as noList,
toStringList([null, null]) as nullsInList,
toStringList(['already a string', 2, date({year:1955, month:11, day:5}), null, ['A','B']]) as mixedList

Result
noList	nullsInList	mixedList
`<null>`	`[<null>,<null>]`	`["already a string","2","1955-11-05",<null>,<null>]`
Rows: 1