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:

graph list functions

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

CREATE
  (alice:Person:Developer {name:'Alice', age: 38, eyes: 'brown'}),
  (bob {name: 'Bob', age: 25, eyes: 'blue'}),
  (charlie {name: 'Charlie', age: 53, eyes: 'green'}),
  (daniel {name: 'Daniel', age: 54, eyes: 'brown'}),
  (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:KNOWS]->(charlie),
  (bob)-[:KNOWS]->(daniel),
  (charlie)-[:KNOWS]->(daniel),
  (bob)-[:MARRIED]->(eskil)

keys()

keys returns a LIST<STRING> containing the string representations for all the property names of a NODE, RELATIONSHIP, or MAP.

Syntax:

keys(expression)

Returns:

LIST<STRING>

Arguments:

Name Description

expression

An expression that returns a NODE, RELATIONSHIP, or MAP.

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.

Table 1. Result
keys(a)

["eyes","name","age"]

Rows: 1

labels()

labels returns a LIST<STRING> containing the string representations for all the labels of a NODE.

Syntax:

labels(node)

Returns:

LIST<STRING>

Arguments:

Name Description

node

An expression that returns a single NODE.

Considerations:

labels(null) returns null.
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.

Table 2. Result
labels(a)

["Person","Developer"]

Rows: 1

nodes()

nodes() returns a LIST<NODE> containing all the NODE values in a PATH.

Syntax:

nodes(path)

Returns:

LIST<NODE>

Arguments:

Name Description

path

An expression that returns a PATH.

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.

Table 3. Result
nodes(p)

[(:Person:Developer {name: "Alice",eyes: "brown",age: 38}), ({name: "Bob",eyes: "blue",age: 25}), ({array: ['one', 'two', 'three'],name: "Eskil",eyes: "blue",age: 41})]

Rows: 1

range()

range() returns a LIST<INTEGER> comprising all INTEGER values within a range bounded by a start value and an end value, where the difference step between any two consecutive values is constant; i.e. an arithmetic progression. 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).

Syntax:

range(start, end [, step])

Returns:

LIST<INTEGER>

Arguments:

Name Description

start

An expression that returns an INTEGER value.

end

An expression that returns an INTEGER value.

step

A numeric expression defining the difference between any two consecutive values, with a default of 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.

Table 4. 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()

reduce() returns the value resulting from the application of an expression on each successive element in a list in conjunction with the result of the computation thus far. This function will iterate through each element e in the given list, run the expression on e — taking into account the current partial result — and store the new partial result in the accumulator. This function is analogous to the fold or reduce method in functional languages such as Lisp and Scala.

Syntax:

reduce(accumulator = initial, variable IN list | expression)

Returns:

The type of the value returned depends on the arguments provided, along with the semantics of expression.

Arguments:

Name Description

accumulator

A variable that will hold the result and the partial results as the list is iterated.

initial

An expression that runs once to give a starting value to the accumulator.

list

An expression that returns a LIST<ANY>.

variable

The closure will have a variable introduced in its context. We decide here which variable to use.

expression

This expression will run once per value in the list, and produce the result value.
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.

Table 5. Result
reduction

117

Rows: 1

relationships()

relationships() returns a LIST<RELATIONSHIP> containing all the RELATIONSHIP values in a PATH..

Syntax:

relationships(path)

Returns:

LIST<RELATIONSHIP>

Arguments:

Name Description

path

An expression that returns a PATH.

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.

Table 6. Result
relationships(p)

[:KNOWS[0]{},:MARRIED[4]{}]

Rows: 1

reverse()

reverse() returns a LIST<ANY> in which the order of all elements in the given LIST<ANY> have been reversed.

Syntax:

reverse(original)

Returns:

A LIST<ANY> containing homogeneous or heterogeneous elements; the types of the elements are determined by the elements within original.

Arguments:

Name Description

original

An expression that returns a LIST<ANY>.

Considerations:

Any null element in original is preserved.
Example 7. reverse()
Query
WITH [4923,'abc',521, null, 487] AS ids
RETURN reverse(ids)
Table 7. Result
reverse(ids)

[487,<null>,521,"abc",4923]

Rows: 1

tail()

tail() returns a LIST<ANY> lresult containing all the elements, excluding the first one, from a list list.

Syntax:

tail(list)

Returns:

A LIST<ANY> containing heterogeneous elements; the types of the elements are determined by the elements in list.

Arguments:

Name Description

list

An expression that returns a LIST<ANY>.
Example 8. tail()
Query
MATCH (a) WHERE a.name = 'Eskil'
RETURN a.array, tail(a.array)

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

Table 8. Result
a.array tail(a.array)

["one","two","three"]

["two","three"]

Rows: 1

toBooleanList()

toBooleanList() converts a LIST<ANY> and returns a LIST<BOOLEAN>. If any values are not convertible to BOOLEAN they will be null in the LIST<BOOLEAN> returned.

Syntax:

toBooleanList(list)

Returns:

A LIST<BOOLEAN> containing the converted elements; depending on the input value a converted value is either a BOOLEAN value or null.

Arguments:

Name Description

list

An expression that returns a LIST<ANY>.

Considerations:

Any null element in list is preserved.

Any BOOLEAN 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 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
Table 9. Result
noList nullsInList mixedList

<null>

[<null>,<null>]

[<null>,true,false,<null>,<null>]

Rows: 1

toFloatList()

toFloatList() converts a LIST<ANY> of values and returns a LIST<FLOAT>. If any values are not convertible to FLOAT they will be null in the LIST<FLOAT> returned.

Syntax:

toFloatList(list)

Returns:

A LIST<FLOAT> containing the converted elements; depending on the input value a converted value is either a FLOAT value or null.

Arguments:

Name Description

list

An expression that returns a LIST<ANY>.

Considerations:

Any null element in list is preserved.

Any FLOAT 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 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
Table 10. Result
noList nullsInList mixedList

<null>

[<null>,<null>]

[<null>,2.5,3.14159,<null>,<null>]

Rows: 1

toIntegerList()

toIntegerList() converts a LIST<ANY> of values and returns a LIST<INTEGER>. If any values are not convertible to INTEGER they will be null in the LIST<INTEGER> returned.

Syntax:

toIntegerList(list)

Returns:

A LIST<INTEGER> containing the converted elements; depending on the input value a converted value is either an INTEGER value or null.

Arguments:

Name Description

list

An expression that returns a LIST<ANY>.

Considerations:

Any null element in list is preserved.

Any INTEGER 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 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
Table 11. Result
noList nullsInList mixedList

<null>

[<null>,<null>]

[<null>,2,5,<null>,<null>]

Rows: 1

toStringList()

toStringList() converts a LIST<ANY> of values and returns a LIST<STRING>. If any values are not convertible to STRING they will be null in the LIST<STRING> returned.

Syntax:

toStringList(list)

Returns:

A LIST<STRING> containing the converted elements; depending on the input value a converted value is either a STRING value or null.

Arguments:

Name Description

list

An expression that returns a LIST<ANY>.

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
Table 12. Result
noList nullsInList mixedList

<null>

[<null>,<null>]

["already a string","2","1955-11-05",<null>,<null>]

Rows: 1