List functions

List functions return lists of things — nodes in a path, and so on.

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

keys()

keys returns a list containing the string representations for all the property names of a node, relationship, or map.

Syntax:

keys(expression)

Returns:

A list containing String elements.

Arguments:

Name Description

expression

An expression that returns a node, a relationship, or a map.

Considerations:

keys(null) returns null.
Example 1. keys()
Query
MATCH (a) WHERE a.name = 'Alice'
RETURN keys(a)

A list containing the names of all the properties on the node bound to a is returned.

Table 1. Result
keys(a)

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

Rows: 1

labels()

labels returns a list containing the string representations for all the labels of a node.

Syntax:

labels(node)

Returns:

A list containing String elements.

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 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 containing all the nodes in a path.

Syntax:

nodes(path)

Returns:

A list containing Node elements.

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 containing all the nodes in the path p is returned.

Table 3. Result
nodes(p)

[Node[0]{name:"Alice",age:38,eyes:"brown"},Node[1]{name:"Bob",age:25,eyes:"blue"},Node[4]{eyes:"blue",array:["one","two","three"],name:"Eskil",age:41}]

Rows: 1

range()

range() returns a list comprising all integer values within a range bounded by a start value start and end value end, 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:

A list of Integer elements.

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.

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 nodes in the path are summed and returned as a single value.

Table 5. Result
reduction

117

Rows: 1

relationships()

relationships() returns a list containing all the relationships in a path.

Syntax:

relationships(path)

Returns:

A list containing Relationship elements.

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 containing all the relationships in the path p is returned.

Table 6. Result
relationships(p)

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

Rows: 1

reverse()

reverse() returns a list in which the order of all elements in the original list have been reversed.

Syntax:

reverse(original)

Returns:

A list 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.

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 lresult containing all the elements, excluding the first one, from a list list.

Syntax:

tail(list)

Returns:

A list 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.
Example 8. tail()
Query
MATCH (a) WHERE a.name = 'Eskil'
RETURN a.array, tail(a.array)

The property named array and a list 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 of values and returns a list of boolean values. If any values are not convertible to boolean they will be null in the list returned.

Syntax:

toBooleanList(list)

Returns:

A list 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.

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, 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 of values and returns a list of floating point values. If any values are not convertible to floating point they will be null in the list returned.

Syntax:

toFloatList(list)

Returns:

A list containing the converted elements; depending on the input value a converted value is either a floating point value or null.

Arguments:

Name Description

list

An expression that returns a list.

Considerations:

Any null element in list is preserved.

Any floating point value in list is preserved.

If the list is null, null will be returned.

If the list is not a list, 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 of values and returns a list of integer values. If any values are not convertible to integer they will be null in the list returned.

Syntax:

toIntegerList(list)

Returns:

A list containing the converted elements; depending on the input value a converted value is either a integer value or null.

Arguments:

Name Description

list

An expression that returns a list.

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, 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 of values and returns a list of string values. If any values are not convertible to string they will be null in the list returned.

Syntax:

toStringList(list)

Returns:

A list 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.

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