15.23. Functions

Prev		Next

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`

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.array	head(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.array	last(a.array)
1 row
0 ms
`["one","two","three"]`	`"three"`

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

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.array	filter(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.array	tail(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.age	c.age	abs(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`

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`