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

Figure 3.19. Graph
alt

3.4.4.1. extract()

To return a single property, or the value of a function from a list of nodes or relationships, you can use extract(). It will go through a list, run an expression on every element, and return the results in a list with these values. It works like the map method in functional languages such as Lisp and Scala.

Syntax: extract( variable IN list | expression )

Arguments:

Name Description

list

An expression that returns a list

variable

The closure will have a variable introduced in its context. Here you decide which variable to use.

expression

This expression will run once per value in the list, and produces the result list.

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 the path are returned.

Result. 

+------------+
| extracted  |
+------------+
| [38,25,54] |
+------------+
1 row

3.4.4.2. filter()

filter() returns all the elements in a list that comply to a predicate.

Syntax: filter(variable IN list WHERE predicate)

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 items in the list.

Query. 

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

This returns the property named array and a list of values in it, which have size '3'.

Result. 

+----------------------------------------------------------------+
| a.array               | filter(x IN a.array WHERE size(x) = 3) |
+----------------------------------------------------------------+
| ["one","two","three"] | ["one","two"]                          |
+----------------------------------------------------------------+
1 row

3.4.4.3. keys()

Returns a list of string representations for the property names of a node, relationship, or map.

Syntax: keys( expression )

Arguments:

Name Description

expression

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

Query. 

MATCH (a)
WHERE a.name = 'Alice'
RETURN keys(a)

The name of the properties of n is returned by the query.

Result. 

+-----------------------+
| keys(a)               |
+-----------------------+
| ["name","age","eyes"] |
+-----------------------+
1 row

3.4.4.4. labels()

Returns a list of string representations for the labels attached to a node.

Syntax: labels( node )

Arguments:

Name Description

node

Any expression that returns a single node

Query. 

MATCH (a)
WHERE a.name = 'Alice'
RETURN labels(a)

The labels of n is returned by the query.

Result. 

+---------------+
| labels(a)     |
+---------------+
| ["bar","foo"] |
+---------------+
1 row

3.4.4.5. nodes()

Returns all nodes in a path.

Syntax: nodes( path )

Arguments:

Name Description

path

A path.

Query. 

MATCH p =(a)-->(b)-->(c)
WHERE a.name = 'Alice' AND c.name = 'Eskil'
RETURN nodes(p)

All the nodes in the path p are returned by the example query.

Result. 

+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| nodes(p)                                                                                                                                                |
+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| [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"}] |
+---------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row

3.4.4.6. range()

range() returns numerical values in a range. The default distance between values in the range is 1. The range is inclusive in both ends.

Syntax: range( start, end [, step] )

Arguments:

Name Description

start

A numerical expression.

end

A numerical expression.

step

A numerical expression.

Query. 

RETURN range(0, 10), range(2, 18, 3)

Two lists of numbers in the given ranges are returned.

Result. 

+---------------------------------------------+
| range(0, 10)             | range(2, 18, 3)  |
+---------------------------------------------+
| [0,1,2,3,4,5,6,7,8,9,10] | [2,5,8,11,14,17] |
+---------------------------------------------+
1 row

3.4.4.7. reduce()

To run an expression against individual elements of a list, and store the result of the expression in an accumulator, you can use reduce(). It will go through a list, run an expression on every element, storing the partial result in the accumulator. It works like the fold or reduce method in functional languages such as Lisp and Scala.

Syntax: reduce( accumulator = initial, variable IN list | 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. Here you decide which variable to use.

expression

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

Result. 

+-----------+
| reduction |
+-----------+
| 117       |
+-----------+
1 row

3.4.4.8. relationships()

Returns all relationships in a path.

Syntax: relationships( path )

Arguments:

Name Description

path

A path.

Query. 

MATCH p =(a)-->(b)-->(c)
WHERE a.name = 'Alice' AND c.name = 'Eskil'
RETURN relationships(p)

All the relationships in the path p are returned.

Result. 

+-----------------------------+
| relationships(p)            |
+-----------------------------+
| [:KNOWS[0]{},:MARRIED[4]{}] |
+-----------------------------+
1 row

3.4.4.9. tail()

tail() returns all but the first element in a list.

Syntax: tail( expression )

Arguments:

Name Description

expression

This expression should return a list of some kind.

Query. 

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.array, tail(a.array)

This returns the property named array and all elements of that property except the first one.

Result. 

+-----------------------------------------+
| a.array               | tail(a.array)   |
+-----------------------------------------+
| ["one","two","three"] | ["two","three"] |
+-----------------------------------------+
1 row