3.4.4. 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 Section 3.2.8, “Lists” and Section 3.2.5.7, “List operators”.

The function rels() has been superseded by relationships(), and will be removed in a future release.

Functions:

Figure 3.22. Graph
alt

3.4.4.1. extract()

extract() returns a list lresult containing the values resulting from an expression which has been applied to each element in a list list. This function is analogous to the map method in functional languages such as Lisp and Scala.

Syntax: extract(variable IN list | expression)

Returns:

A list containing heterogeneous elements; the types of the elements are determined by expression.

Arguments:

Name Description

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 list, and add it to the list which is returned by extract().

Considerations:

Any null values in list are preserved.

Common usages of extract() include:

  • Returning a property from a list of nodes or relationships; for example, expression = n.prop and list = nodes(<some-path>).
  • Returning the result of the application of a function on each element in a list; for example, expression = toUpper(x) and variable = x.

Query. 

MATCH p =(a)-->(b)-->(c)
WHERE a.name = 'Alice' AND b.name = 'Bob' AND c.name = 'Daniel'
RETURN extract(n IN nodes(p)| n.age) AS extracted

The age property of all nodes in path p are returned.

Table 3.147. Result
extracted

1 row

[38,25,54]

Try this query live.  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) MATCH p = (a)-->(b)-->(c) WHERE a.name = 'Alice' AND b.name = 'Bob' AND c.name = 'Daniel' RETURN extract(n IN nodes(p) | n.age) AS extracted

3.4.4.2. filter()

filter() returns a list lresult containing all the elements from a list list that comply with the given predicate.

Syntax: filter(variable IN list WHERE predicate)

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.

variable

This is the variable that can be used from the predicate.

predicate

A predicate that is tested against all elements in list.

Query. 

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.array, filter(x IN a.array WHERE size(x)= 3)

The property named array and a list of all values having size '3' are returned.

Table 3.148. Result
a.array filter(x IN a.array WHERE size(x) = 3)

1 row

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

["one","two"]

Try this query live.  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) MATCH (a) WHERE a.name = 'Eskil' RETURN a.array, filter(x IN a.array WHERE size(x) = 3)

3.4.4.3. 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 3.149. Result
keys(a)

1 row

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

Try this query live.  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) MATCH (a) WHERE a.name = 'Alice' RETURN keys(a)

3.4.4.4. 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 3.150. Result
labels(a)

1 row

["Person","Developer"]

Try this query live.  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) MATCH (a) WHERE a.name = 'Alice' RETURN labels(a)

3.4.4.5. 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.151. Result
nodes(p)

1 row

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

Try this query live.  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) MATCH p = (a)-->(b)-->(c) WHERE a.name = 'Alice' AND c.name = 'Eskil' RETURN nodes(p)

3.4.4.6. 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. The range is inclusive, and the arithmetic progression will therefore always contain start and — depending on the values of start, step and end — end.

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)

Two lists of numbers in the given ranges are returned.

Table 3.152. Result
range(0, 10) range(2, 18, 3)

1 row

[0,1,2,3,4,5,6,7,8,9,10]

[2,5,8,11,14,17]

Try this query live.  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) RETURN range(0, 10), range(2, 18, 3)

3.4.4.7. 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 3.153. Result
reduction

1 row

117

Try this query live.  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) 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

3.4.4.8. 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 3.154. Result
relationships(p)

1 row

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

Try this query live.  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) MATCH p = (a)-->(b)-->(c) WHERE a.name = 'Alice' AND c.name = 'Eskil' RETURN relationships(p)

3.4.4.9. 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 3.155. Result
reverse(ids)

1 row

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

Try this query live.  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) WITH [4923,'abc',521, null, 487] AS ids RETURN reverse(ids)

3.4.4.10. 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 3.156. Result
a.array tail(a.array)

1 row

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

["two","three"]

Try this query live.  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) MATCH (a) WHERE a.name = 'Eskil' RETURN a.array, tail(a.array)