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:Adminstrator {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)

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 1. 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 2. 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 3. 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 4. 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 5. 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 6. 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 7. 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 8. 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 `list` is done according to the `toBooleanOrNull()` function.

Example 9. 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>` 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`	`LIST<ANY>`	A list of values to be converted into a list of floats.
Returns	`LIST<FLOAT>`

Considerations
Any `null` element in `list` is preserved.
Any `FLOAT` value in `list` 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 `toFloatOrNull()` function.

Example 10. 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>` 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`	`LIST<ANY>`	A list of values 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 `LIST<ANY>`, an error will be returned.
The conversion for each value in `list` is done according to the `toIntegerOrNull()` function.

Example 11. 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 `list` is preserved.
Any `STRING` value in `list` is preserved.
If the `list` is `null`, `null` will be returned.
If the `list` is not a `LIST<ANY>`, an error will be returned.
The conversion for each value in `list` is done according to the `toStringOrNull()` function.

Example 12. 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