14.29. Functions

14.29.1. Predicates
14.29.2. Scalar functions
14.29.3. Collection functions
14.29.4. Mathematical functions
14.29.5. String 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

Figure 14.12. Graph


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

See also Section 14.1.2, “Comparison operators”.

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. 

MATCH p=a-[*1..3]->b
WHERE a.name='Alice' and b.name='Daniel' and 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
2 ms

[Node[3]{name:"Alice",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"Charlie",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"Daniel",age:54,eyes:"brown"}]


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. 

MATCH a
WHERE a.name='Eskil' and 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
1 ms

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


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. 

MATCH p=n-[*1..3]->b
WHERE n.name='Alice' and 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
2 ms

[Node[3]{name:"Alice",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"Charlie",age:53,eyes:"green"}]

[Node[3]{name:"Alice",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"Charlie",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"Daniel",age:54,eyes:"brown"}]


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. 

MATCH p=n-->b
WHERE n.name='Alice' and 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:"Alice",age:38,eyes:"brown"},:KNOWS[0] {},Node[4]{name:"Bob",age:25,eyes:"blue"}]


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

MATCH p=a-->b-->c
WHERE a.name='Alice'
RETURN length(p)

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

Result

length(p)
3 rows
1 ms

2

2

2


TYPE

Returns a string representation of the relationship type.

Syntax: TYPE( relationship )

Arguments:

  • relationship: A relationship.

Query. 

MATCH (n)-[r]->()
WHERE n.name='Alice'
RETURN type(r)

The relationship type of r is returned by the query.

Result

type(r)
2 rows
1 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. 

MATCH a
RETURN ID(a)

This returns the node id for three nodes.

Result

ID(a)
5 rows
1 ms

1

2

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. 

MATCH a
WHERE a.name='Alice'
RETURN coalesce(a.hairColour?, a.eyes?)

Result

coalesce(a.hairColour?, a.eyes?)
1 row
1 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. 

MATCH a
WHERE a.name='Eskil'
RETURN a.array, head(a.array)

The first node in the path is returned.

Result

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

MATCH a
WHERE a.name='Eskil'
RETURN a.array, last(a.array)

The last node in the path is returned.

Result

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

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

"three"


14.29.3. Collection functions

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

See also Section 14.1.4, “Collection operators”.

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
1 ms

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


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
1 ms

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


LABELS

Returns a collection 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
1 ms

["foo","bar"]


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. 

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)

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

Result

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

[38,25,54]


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. 

MATCH a
WHERE a.name='Eskil'
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. 

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

MATCH n
RETURN range(0,10), range(2,18,3)
LIMIT 1

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]


REDUCE

To run an expression against individual elements of a collection, and store the result of the expression in an accumulator, you can use REDUCE. It will go through a collection, 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, identifier in collection : expression )

Arguments:

  • accumulator: An identifier that will hold the result and the partial results as the collection is iterated
  • initial: An expression that runs once to give a starting value to the accumulator
  • 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 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)

The age property of all nodes in the path are summed and returned as a single value.

Result

reduce(totalAge = 0, n in nodes(p) : totalAge + n.age)
1 row
1 ms

117


14.29.4. Mathematical functions

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

See also Section 14.1.1, “Mathematical operators”.

ABS

ABS returns the absolute value of a number.

Syntax: ABS( expression )

Arguments:

  • expression: A numeric expression.

Query. 

MATCH a, e
WHERE a.name = 'Alice' and e.name = 'Eskil'
RETURN a.age, e.age, abs(a.age - e.age)

The absolute value of the age difference is returned.

Result

a.agee.ageabs(a.age - e.age)
1 row
1 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. 

MATCH a
RETURN round(3.141592)
LIMIT 1

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. 

MATCH n
RETURN sqrt(256)
LIMIT 1

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. 

MATCH n
RETURN sign(-17), sign(0.1)
LIMIT 1

Result

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

-1.0

1.0


14.29.5. String functions

These functions all operate on string expressions only, and will return an error if used on any other values. Except STR(), which converts to strings.

See also Section 14.1.3, “String operators”.

STR

STR returns a string representation of the expression.

Syntax: STR( expression )

Arguments:

  • expression: An expression that returns anything

Query. 

MATCH a
RETURN str(1)
LIMIT 1

A string.

Result

str(1)
1 row
0 ms

"1"


REPLACE

REPLACE returns a string with the search string replaced by the replace string. It replaces all occurrences.

Syntax: REPLACE( original, search, replace )

Arguments:

  • original: An expression that returns a string
  • search: An expression that returns a string to search for
  • replace: An expression that returns the string to replace the search string with

Query. 

MATCH a
RETURN replace("hello", "l", "w")
LIMIT 1

A string.

Result

replace("hello", "l", "w")
1 row
0 ms

"hewwo"


SUBSTRING

SUBSTRING returns a substring of the original, with a 0-based index start and length. If length is omitted, it returns a substring from start until the end of the string.

Syntax: SUBSTRING( original, start [, length] )

Arguments:

  • original: An expression that returns a string
  • start: An expression that returns a positive number
  • length: An expression that returns a positive number

Query. 

MATCH n
RETURN substring("hello", 1, 3), substring("hello", 2)
LIMIT 1

A string.

Result

substring("hello", 1, 3)substring("hello", 2)
1 row
0 ms

"ell"

"llo"


LEFT

LEFT returns a string containing the left n characters of the original string.

Syntax: LEFT( original, length )

Arguments:

  • original: An expression that returns a string
  • n: An expression that returns a positive number

Query. 

MATCH n
RETURN left("hello", 3)
LIMIT 1

A String.

Result

left("hello", 3)
1 row
0 ms

"hel"


RIGHT

RIGHT returns a string containing the right n characters of the original string.

Syntax: RIGHT( original, length )

Arguments:

  • original: An expression that returns a string
  • n: An expression that returns a positive number

Query. 

MATCH n
RETURN right("hello", 3)
LIMIT 1

A string.

Result

right("hello", 3)
1 row
0 ms

"llo"


LTRIM

LTRIM returns the original string with whitespace removed from the left side.

Syntax: LTRIM( original )

Arguments:

  • original: An expression that returns a string

Query. 

MATCH n
RETURN ltrim("   hello")
LIMIT 1

A string.

Result

ltrim(" hello")
1 row
0 ms

"hello"


RTRIM

RTRIM returns the original string with whitespace removed from the right side.

Syntax: RTRIM( original )

Arguments:

  • original: An expression that returns a string

Query. 

MATCH n
RETURN rtrim("hello   ")
LIMIT 1

A string.

Result

rtrim("hello ")
1 row
0 ms

"hello"


TRIM

TRIM returns the original string with whitespace removed from both sides.

Syntax: TRIM( original )

Arguments:

  • original: An expression that returns a string

Query. 

MATCH n
RETURN trim("   hello   ")
LIMIT 1

A string.

Result

trim(" hello ")
1 row
0 ms

"hello"


LOWER

LOWER returns the original string in lowercase.

Syntax: LOWER( original )

Arguments:

  • original: An expression that returns a string

Query. 

MATCH n
RETURN lower("HELLO")
LIMIT 1

A string.

Result

lower("HELLO")
1 row
0 ms

"hello"


UPPER

UPPER returns the original string in uppercase.

Syntax: UPPER( original )

Arguments:

  • original: An expression that returns a string

Query. 

MATCH a
RETURN upper("hello")
LIMIT 1

A string.

Result

upper("hello")
1 row
0 ms

"HELLO"


Case Expressions

Cypher supports CASE expressions, which is a generic conditional expression, similar to if/else statements in other languages. Two variants of CASE exist - the simple form and the generic form.

Simple CASE

The expression is calculated, and compared in order with the WHEN clauses until a match is found. If no match is found the expression in the ELSE clause is used, or null, if no ELSE case exists.

Syntax: +CASE+ in +WHEN+ value +THEN+ result [+WHEN+ ...] [+ELSE+ default] +END+

Arguments:

  • in: A valid expression
  • value: An expression whose result will be compared to expression
  • result: This is the result expression used if the value expression matches the in expression
  • default: The expression to use if no match is found.

Query. 

MATCH n
RETURN CASE n.eyes
WHEN 'blue'  THEN 1
WHEN 'brown' THEN 2
ELSE 3
END as result

A string.

Result

result
5 rows
1 ms

2

1

2

1

3


Generic CASE

The predicates are evaluated in order until a true value is found, and the result value is used.If no match is found the expression in the +ELSE + clause is used, or null, if no + ELSE + case exists.

Syntax: +CASE+ +WHEN+ predicate +THEN+ result [+WHEN+ ...] [+ELSE+ result] +END+

Arguments:

  • predicate: A predicate that is tested to find a valid alternative
  • result: This is the result expression used if the predicate matches
  • default: The expression to use if no match is found.

Query. 

MATCH n
RETURN CASE
WHEN n.eyes = 'blue'  THEN 1
WHEN n.age < 40       THEN 2
ELSE 3
END as result

A string.

Result

result
5 rows
1 ms

3

1

2

1

3