13.3. List functions

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

See also the section called “List operators”.

Figure 13.3. Graph

cypher-functions-graph.svg

nodes()

Returns all nodes in a path.

Syntax: nodes( path )

Arguments:

  • 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)
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 (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match p=(a)-->(b)-->(c) where a.name='Alice' and c.name='Eskil' return nodes(p)

relationships()

Returns all relationships in a path.

Syntax: relationships( path )

Arguments:

  • 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)
1 row

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match p=(a)-->(b)-->(c) where a.name='Alice' and c.name='Eskil' return relationships(p)

labels()

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

Syntax: labels( node )

Arguments:

  • 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)
1 row

["bar","foo"]

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Alice' return labels(a)

keys()

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

Syntax: keys( property-container )

Arguments:

  • property-container: A node, a relationship, or a literal 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)
1 row

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Alice' return keys(a)

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:

  • list: An expression that returns a list
  • variable: The closure will have a variable introduced in it’s 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
1 row

[38,25,54]

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; 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

filter()

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

Syntax: filter(variable IN list WHERE predicate)

Arguments:

  • 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.arrayfilter(x in a.array WHERE size(x) = 3)
1 row

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

["one","two"]

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Eskil' return a.array, filter(x in a.array WHERE size(x) = 3)

tail()

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

Syntax: tail( expression )

Arguments:

  • 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.arraytail(a.array)
1 row

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

["two","three"]

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Eskil' return a.array, tail(a.array)

range()

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

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

Arguments:

  • 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)
1 row

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

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; return range(0,10), range(2,18,3)

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:

  • 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 it’s 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
1 row

117

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; 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