# 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.

Functions: ## 1. 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`.
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

## 2. 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`.
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

## 3. 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`.
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{name:"Alice",age:38,eyes:"brown"},Node{name:"Bob",age:25,eyes:"blue"},Node{eyes:"blue",array:["one","two","three"],name:"Eskil",age:41}]`

Rows: 1

## 4. 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`.

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

## 5. 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.

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

## 6. 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`.
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{},:MARRIED{}]`

Rows: 1

## 7. 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.
Query
``````WITH [4923,'abc',521, null, 487] AS ids
RETURN reverse(ids)``````
Table 7. Result
reverse(ids)

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

Rows: 1

## 8. 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.

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

## 9. 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.
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

## 10. 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.
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

## 11. 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.
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

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