List functions

List functions return lists of different data entities.

Further details and examples of lists may be found in Lists and List operators.

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
`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, variable)`
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.
	`variable`	`LIST<ANY>`	A variable that can be used within the reducing expression.
Returns	`ANY`

This function is analogous to the fold or reduce method 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