List functions

Further details and examples of lists may be found in Lists and List operators.

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

The functions extract() and filter() have been deprecated and will be removed in a future release. Consider using a list comprehension (e.g. [x IN xs WHERE predicate | extraction]) instead.

Functions:

Graph
  N0 [
    label = "{Person, Developer|name = \'Alice\'\leyes = \'brown\'\lage = 38\l}"
  ]
  N0 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N0 -> N1 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N1 [
    label = "name = \'Bob\'\leyes = \'blue\'\lage = 25\l"
  ]
  N1 -> N4 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "MARRIED\n"
  ]
  N1 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N2 [
    label = "name = \'Charlie\'\leyes = \'green\'\lage = 53\l"
  ]
  N2 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N3 [
    label = "name = \'Daniel\'\leyes = \'brown\'\lage = 54\l"
  ]
  N4 [
    label = "array = \[\'one\', \'two\', \'three\'\]\lname = \'Eskil\'\leyes = \'blue\'\lage = 41\l"
  ]

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. Note that this function has been deprecated, consider using a list comprehension (e.g. [variable IN list | expression]) instead.

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 1. Result
extracted

[38,25,54]

1 row

filter()

filter() returns a list lresult containing all the elements from a list list that comply with the given predicate. Note that this function has been deprecated, consider using a list comprehension (e.g. [variable IN list WHERE predicate]) instead.

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 2. Result
a.array filter(x IN a.array WHERE size(x)= 3)

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

["one","two"]

1 row

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

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

1 row

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

["Person","Developer"]

1 row

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

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

1 row

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

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

117

1 row

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

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

1 row

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

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

1 row

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

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

["two","three"]

1 row