## 15.23. Functions

15.23.1. Predicates
15.23.2. Scalar functions
15.23.3. Collection functions
15.23.4. Mathematical functions

Most functions in Cypher will return `null` if the input parameter is `null`.

Here is a list of the functions in Cypher, seperated into three different sections: Predicates, Scalar functions and Aggregated functions

Graph

### 15.23.1. Predicates

Predicates are boolean functions that return true or false for a given set of input. They are most commonly used to filter out subgraphs in the `WHERE` part of a query.

#### ALL

Tests whether a predicate holds for all element of this collection collection.

Syntax: `ALL(identifier in collection WHERE predicate)`

Arguments:

• collection: An expression that returns a collection
• identifier: This is the identifier that can be used from the predicate.
• predicate: A predicate that is tested against all items in the collection.

Query

```START a=node(3), b=node(1)
MATCH p=a-[*1..3]->b
WHERE all(x in nodes(p)
WHERE x.age > 30)
RETURN p```

All nodes in the returned paths will have an `age` property of at least 30.

Result

p
1 row
0 ms

`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"D",age:54,eyes:"brown"}]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3), b=node(1) match p=a-[*1..3]->b where all(x in nodes(p) WHERE x.age > 30) return p

#### ANY

Tests whether a predicate holds for at least one element in the collection.

Syntax: `ANY(identifier in collection WHERE predicate)`

Arguments:

• collection: An expression that returns a collection
• identifier: This is the identifier that can be used from the predicate.
• predicate: A predicate that is tested against all items in the collection.

Query

```START a=node(2)
WHERE any(x in a.array
WHERE x = "one")
RETURN a```

All nodes in the returned paths has at least one `one` value set in the array property named `array`.

Result

a
1 row
0 ms

`Node[2]{name:"E",age:41,eyes:"blue",array:["one","two","three"]}`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(2) where any(x in a.array WHERE x = "one") return a

#### NONE

Returns true if the predicate holds for no element in the collection.

Syntax: `NONE(identifier in collection WHERE predicate)`

Arguments:

• collection: An expression that returns a collection
• identifier: This is the identifier that can be used from the predicate.
• predicate: A predicate that is tested against all items in the collection.

Query

```START n=node(3)
MATCH p=n-[*1..3]->b
WHERE NONE(x in nodes(p)
WHERE x.age = 25)
RETURN p```

No nodes in the returned paths has a `age` property set to `25`.

Result

p
2 rows
0 ms

`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"}]`

`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"D",age:54,eyes:"brown"}]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start n=node(3) match p=n-[*1..3]->b where NONE(x in nodes(p) WHERE x.age = 25) return p

#### SINGLE

Returns true if the predicate holds for exactly one of the elements in the collection.

Syntax: `SINGLE(identifier in collection WHERE predicate)`

Arguments:

• collection: An expression that returns a collection
• identifier: This is the identifier that can be used from the predicate.
• predicate: A predicate that is tested against all items in the collection.

Query

```START n=node(3)
MATCH p=n-->b
WHERE SINGLE(var in nodes(p)
WHERE var.eyes = "blue")
RETURN p```

Exactly one node in every returned path will have the `eyes` property set to `"blue"`.

Result

p
1 row
0 ms

`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[0] {},Node[4]{name:"B",age:25,eyes:"blue"}]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start n=node(3) match p=n-->b where SINGLE(var in nodes(p) WHERE var.eyes = "blue") return p

### 15.23.2. Scalar functions

Scalar functions return a single value.

#### LENGTH

To return or filter on the length of a collection, use the `LENGTH()` function.

Syntax: `LENGTH( collection )`

Arguments:

• collection: An expression that returns a collection

Query

```START a=node(3)
MATCH p=a-->b-->c
RETURN length(p)```

The length of the path `p` is returned by the query.

Result

length(p)
3 rows
0 ms

`2`

`2`

`2`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3) match p=a-->b-->c return length(p)

#### TYPE

Returns a string representation of the relationship type.

Syntax: `TYPE( relationship )`

Arguments:

• relationship: A relationship.

Query

```START n=node(3)
MATCH (n)-[r]->()
RETURN type(r)```

The relationship type of `r` is returned by the query.

Result

type(r)
2 rows
0 ms

`"KNOWS"`

`"KNOWS"`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start n=node(3) match (n)-[r]->() return type(r)

#### ID

Returns the id of the relationship or node.

Syntax: `ID( property-container )`

Arguments:

• property-container: A node or a relationship.

Query

```START a=node(3, 4, 5)
RETURN ID(a)```

This returns the node id for three nodes.

Result

ID(a)
3 rows
0 ms

`3`

`4`

`5`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3, 4, 5) return ID(a)

#### COALESCE

Returns the first non-`null` value in the list of expressions passed to it.

Syntax: `COALESCE( expression [, expression]* )`

Arguments:

• expression: The expression that might return null.

Query

```START a=node(3)
RETURN coalesce(a.hairColour?, a.eyes?)```

Result

coalesce(a.hairColour?, a.eyes?)
1 row
0 ms

`"brown"`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3) return coalesce(a.hairColour?, a.eyes?)

`HEAD` returns the first element in a collection.

Syntax: `HEAD( expression )`

Arguments:

• expression: This expression should return a collection of some kind.

Query

```START a=node(2)

The first node in the path is returned.

Result

1 row
0 ms

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

`"one"`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(2) return a.array, head(a.array)

#### LAST

`LAST` returns the last element in a collection.

Syntax: `LAST( expression )`

Arguments:

• expression: This expression should return a collection of some kind.

Query

```START a=node(2)
RETURN a.array, last(a.array)```

The last node in the path is returned.

Result

a.arraylast(a.array)
1 row
0 ms

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

`"three"`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(2) return a.array, last(a.array)

### 15.23.3. Collection functions

Collection functions return collections of things — nodes in a path, and so on.

#### NODES

Returns all nodes in a path.

Syntax: `NODES( path )`

Arguments:

• path: A path.

Query

```START a=node(3), c=node(2)
MATCH p=a-->b-->c
RETURN NODES(p)```

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

Result

NODES(p)
1 row
0 ms

`[Node[3]{name:"A",age:38,eyes:"brown"},Node[4]{name:"B",age:25,eyes:"blue"},Node[2]{name:"E",age:41,eyes:"blue",array:["one","two","three"]}]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3), c=node(2) match p=a-->b-->c return NODES(p)

#### RELATIONSHIPS

Returns all relationships in a path.

Syntax: `RELATIONSHIPS( path )`

Arguments:

• path: A path.

Query

```START a=node(3), c=node(2)
MATCH p=a-->b-->c
RETURN RELATIONSHIPS(p)```

All the relationships in the path `p` are returned.

Result

RELATIONSHIPS(p)
1 row
0 ms

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

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3), c=node(2) match p=a-->b-->c return RELATIONSHIPS(p)

#### EXTRACT

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

Syntax: `EXTRACT( identifier in collection : expression )`

Arguments:

• collection: An expression that returns a collection
• identifier: The closure will have an identifier introduced in it’s context. Here you decide which identifier to use.
• expression: This expression will run once per value in the collection, and produces the result collection.

Query

```START a=node(3), b=node(4), c=node(1)
MATCH p=a-->b-->c
RETURN extract(n in nodes(p) : n.age)```

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

Result

extract(n in nodes(p) : n.age)
1 row
0 ms

`[38,25,54]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3), b=node(4), c=node(1) match p=a-->b-->c return extract(n in nodes(p) : n.age)

#### FILTER

`FILTER` returns all the elements in a collection that comply to a predicate.

Syntax: `FILTER(identifier in collection : predicate)`

Arguments:

• collection: An expression that returns a collection
• identifier: This is the identifier that can be used from the predicate.
• predicate: A predicate that is tested against all items in the collection.

Query

```START a=node(2)
RETURN a.array, filter(x in a.array : length(x) = 3)```

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

Result

a.arrayfilter(x in a.array : length(x) = 3)
1 row
0 ms

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

`["one","two"]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(2) return a.array, filter(x in a.array : length(x) = 3)

#### TAIL

`TAIL` returns all but the first element in a collection.

Syntax: `TAIL( expression )`

Arguments:

• expression: This expression should return a collection of some kind.

Query

```START a=node(2)
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
0 ms

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

`["two","three"]`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(2) return a.array, tail(a.array)

#### RANGE

Returns numerical values in a range with a non-zero step value step. Range is inclusive in both ends.

Syntax: `RANGE( start, end [, step] )`

Arguments:

• start: A numerical expression.
• end: A numerical expression.
• step: A numerical expression.

Query

```START n=node(1)
RETURN range(0,10), range(2,18,3)```

Two lists of numbers are returned.

Result

range(0,10)range(2,18,3)
1 row
0 ms

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

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

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start n=node(1) return range(0,10), range(2,18,3)

### 15.23.4. Mathematical functions

These functions all operate on numerical expressions only, and will return an error if used on any other values.

#### ABS

`ABS` returns the absolute value of a number.

Syntax: `ABS( expression )`

Arguments:

• expression: A numeric expression.

Query

```START a=node(3), c=node(2)
RETURN a.age, c.age, abs(a.age - c.age)```

The absolute value of the age difference is returned.

Result

a.agec.ageabs(a.age - c.age)
1 row
0 ms

`38`

`41`

`3.0`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(3), c=node(2) return a.age, c.age, abs(a.age - c.age)

#### ROUND

`ROUND` returns the numerical expression, rounded to the nearest integer.

Syntax: `ROUND( expression )`

Arguments:

• expression: A numerical expression.

Query

```START a=node(1)
RETURN round(3.141592)```

Result

round(3.141592)
1 row
0 ms

`3`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(1) return round(3.141592)

#### SQRT

`SQRT` returns the square root of a number.

Syntax: `SQRT( expression )`

Arguments:

• expression: A numerical expression

Query

```START a=node(1)
RETURN sqrt(256)```

Result

sqrt(256)
1 row
0 ms

`16.0`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start a=node(1) return sqrt(256)

#### SIGN

`SIGN` returns the signum of a number — zero if the expression is zero, `-1` for any negative number, and `1` for any positive number.

Syntax: `SIGN( expression )`

Arguments:

• expression: A numerical expression

Query

```START n=node(1)
RETURN sign(-17), sign(0.1)```

Result

sign(-17)sign(0.1)
1 row
0 ms

`-1.0`

`1.0`

Try this query live. (1) {"age":54,"eyes":"brown","name":"D"} (2) {"age":41,"array":["one","two","three"],"eyes":"blue","name":"E"} (3) {"age":38,"eyes":"brown","name":"A"} (4) {"age":25,"eyes":"blue","name":"B"} (5) {"age":53,"eyes":"green","name":"C"} (3)-[:KNOWS]->(4) {} (3)-[:KNOWS]->(5) {} (4)-[:KNOWS]->(1) {} (4)-[:MARRIED]->(2) {} (5)-[:KNOWS]->(1) {} start n=node(1) return sign(-17), sign(0.1)