15.23. Functions

15.23.1. Predicates
15.23.2. Scalar functions
15.23.3. Iterable 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

cypher-functions-graph.txt.svg

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 iterable collection.

Syntax: ALL(identifier in iterable WHERE predicate)

Arguments:

  • iterable: An array property, or an iterable symbol, or an iterable function.
  • identifier: This is the identifier that can be used from the predicate.
  • predicate: A predicate that is tested against all items in iterable.

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"}]


ANY

Tests whether a predicate holds for at least one element of this iterable collection.

Syntax: ANY(identifier in iterable WHERE predicate)

Arguments:

  • iterable: An array property, or an iterable symbol, or an iterable function.
  • identifier: This is the identifier that can be used from the predicate.
  • predicate: A predicate that is tested against all items in iterable.

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"]}


NONE

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

Syntax: NONE(identifier in iterable WHERE predicate)

Arguments:

  • iterable: An array property, or an iterable symbol, or an iterable function.
  • identifier: This is the identifier that can be used from the predicate.
  • predicate: A predicate that is tested against all items in iterable.

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"}]


SINGLE

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

Syntax: SINGLE(identifier in iterable WHERE predicate)

Arguments:

  • iterable: An array property, or an iterable symbol, or an iterable function.
  • identifier: This is the identifier that can be used from the predicate.
  • predicate: A predicate that is tested against all items in iterable.

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"}]


15.23.2. Scalar functions

Scalar functions return a single value.

LENGTH

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

Syntax: LENGTH( iterable )

Arguments:

  • iterable: An iterable, value or function call.

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


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"


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


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"


HEAD

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)
RETURN a.array, head(a.array)

The first node in the path is returned.

Result

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

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

"one"


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"


15.23.3. Iterable functions

Iterable functions return an iterable 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"]}]


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] {}]


EXTRACT

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

Syntax: EXTRACT( identifier in iterable : expression )

Arguments:

  • iterable: An array property, or an iterable identifier, or an iterable function.
  • 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 iterable, and produces the result iterable.

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]


FILTER

FILTER returns all the elements in an iterable that comply to a predicate.

Syntax: FILTER(identifier in iterable : predicate)

Arguments:

  • iterable: An array property, or an iterable symbol, or an iterable function.
  • identifier: This is the identifier that can be used from the predicate.
  • predicate: A predicate that is tested against all items in iterable.

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"]


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"]


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]


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


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


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


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