4.2. Scalar functions

Scalar functions return a single value.

The length() and size() functions are quite similar, and so it is important to take note of the difference. Owing to backwards compatibility, length() currently works on four types: strings, paths, lists and pattern expressions. However, it is recommended to use length() only for paths, and the size() function for strings, lists and pattern expressions. length() on those types may be deprecated in future.

The timestamp() function returns the equivalent value of datetime().epochMillis.

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

Functions:

Figure 4.2. Graph
alt

4.2.1. coalesce()

coalesce() returns the first non-null value in the given list of expressions.

Syntax: coalesce(expression [, expression]*)

Returns:

The type of the value returned will be that of the first non-null expression.

Arguments:

Name Description

expression

An expression which may return null.

Considerations:

null will be returned if all the arguments are null.

Query.  

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

Table 4.7. Result
coalesce(a.hairColor, a.eyes)

1 row

"brown"

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) WHERE a.name = 'Alice' RETURN coalesce(a.hairColor, a.eyes)

4.2.2. endNode()

endNode() returns the end node of a relationship.

Syntax: endNode(relationship)

Returns:

A Node.

Arguments:

Name Description

relationship

An expression that returns a relationship.

Considerations:

endNode(null) returns null.

Query.  

MATCH (x:Developer)-[r]-()
RETURN endNode(r)

Table 4.8. Result
endNode(r)

2 rows

Node[2]{name:"Charlie",eyes:"green",age:53}

Node[1]{name:"Bob",eyes:"blue",age:25}

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (x:Developer)-[r]-() RETURN endNode(r)

4.2.3. head()

head() returns the first element in a list.

Syntax: head(list)

Returns:

The type of the value returned will be that of the first element of list.

Arguments:

Name Description

list

An expression that returns a list.

Considerations:

head(null) returns null.

If the first element in list is null, head(list) will return null.

Query.  

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

The first element in the list is returned.

Table 4.9. Result
a.array head(a.array)

1 row

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

"one"

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) WHERE a.name = 'Eskil' RETURN a.array, head(a.array)

4.2.4. id()

id() returns the id of a relationship or node.

Syntax: id(expression)

Returns:

An Integer.

Arguments:

Name Description

expression

An expression that returns a node or a relationship.

Considerations:

id(null) returns null.

Query.  

MATCH (a)
RETURN id(a)

The node id for each of the nodes is returned.

Table 4.10. Result
id(a)

5 rows

0

1

2

3

4

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) RETURN id(a)

4.2.5. last()

last() returns the last element in a list.

Syntax: last(expression)

Returns:

The type of the value returned will be that of the last element of list.

Arguments:

Name Description

list

An expression that returns a list.

Considerations:

last(null) returns null.

If the last element in list is null, last(list) will return null.

Query.  

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

The last element in the list is returned.

Table 4.11. Result
a.array last(a.array)

1 row

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

"three"

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) WHERE a.name = 'Eskil' RETURN a.array, last(a.array)

4.2.6. length()

length() returns the length of a path.

Syntax: length(path)

Returns:

An Integer.

Arguments:

Name Description

path

An expression that returns a path.

Considerations:

length(null) returns null.

Query.  

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

The length of the path p is returned.

Table 4.12. Result
length(p)

3 rows

2

2

2

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH p = (a)-->(b)-->(c) WHERE a.name = 'Alice' RETURN length(p)

4.2.7. properties()

properties() returns a map containing all the properties of a node or relationship. If the argument is already a map, it is returned unchanged.

Syntax: properties(expression)

Returns:

A Map.

Arguments:

Name Description

expression

An expression that returns a node, a relationship, or a map.

Considerations:

properties(null) returns null.

Query.  

CREATE (p:Person { name: 'Stefan', city: 'Berlin' })
RETURN properties(p)

Table 4.13. Result
properties(p)

1 row Nodes created: 1 Properties set: 2 Labels added: 1

{city -> "Berlin", name -> "Stefan"}

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) CREATE (p:Person {name: 'Stefan', city: 'Berlin'}) RETURN properties(p)

4.2.8. randomUUID()

randomUUID() returns a randomly-generated Universally Unique Identifier (UUID), also known as a Globally Unique Identifier (GUID). This is a 128-bit value with strong guarantees of uniqueness.

Syntax: randomUUID()

Returns:

A String.

Query.  

RETURN randomUUID() AS uuid

Table 4.14. Result
uuid

1 row

"edaa215c-5544-4a4e-9505-2a2ad9185055"

A randomly-generated UUID is returned.

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN randomUUID() AS uuid

4.2.9. size()

size() returns the number of elements in a list.

Syntax: size(list)

Returns:

An Integer.

Arguments:

Name Description

list

An expression that returns a list.

Considerations:

size(null) returns null.

Query.  

RETURN size(['Alice', 'Bob'])

Table 4.15. Result
size(['Alice', 'Bob'])

1 row

2

The number of elements in the list is returned.

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN size(['Alice', 'Bob'])

4.2.10. size() applied to pattern expression

This is the same size() method as described above, but instead of passing in a list directly, a pattern expression can be provided that can be used in a match query to provide a new set of results. These results are a list of paths. The size of the result is calculated, not the length of the expression itself.

Syntax: size(pattern expression)

Arguments:

Name Description

pattern expression

A pattern expression that returns a list.

Query.  

MATCH (a)
WHERE a.name = 'Alice'
RETURN size((a)-->()-->()) AS fof

Table 4.16. Result
fof

1 row

3

The number of sub-graphs matching the pattern expression is returned.

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) WHERE a.name = 'Alice' RETURN size((a)-->()-->()) AS fof

4.2.11. size() applied to string

size() returns the number of Unicode characters in a string.

Syntax: size(string)

Returns:

An Integer.

Arguments:

Name Description

string

An expression that returns a string value.

Considerations:

size(null) returns null.

Query.  

MATCH (a)
WHERE size(a.name)> 6
RETURN size(a.name)

Table 4.17. Result
size(a.name)

1 row

7

The number of characters in the string 'Charlie' is returned.

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (a) WHERE size(a.name) > 6 RETURN size(a.name)

4.2.12. startNode()

startNode() returns the start node of a relationship.

Syntax: startNode(relationship)

Returns:

A Node.

Arguments:

Name Description

relationship

An expression that returns a relationship.

Considerations:

startNode(null) returns null.

Query.  

MATCH (x:Developer)-[r]-()
RETURN startNode(r)

Table 4.18. Result
startNode(r)

2 rows

Node[0]{name:"Alice",eyes:"brown",age:38}

Node[0]{name:"Alice",eyes:"brown",age:38}

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (x:Developer)-[r]-() RETURN startNode(r)

4.2.13. timestamp()

timestamp() returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Syntax: timestamp()

Returns:

An Integer.

Considerations:

timestamp() will return the same value during one entire query, even for long-running queries.

Query.  

RETURN timestamp()

The time in milliseconds is returned.

Table 4.19. Result
timestamp()

1 row

1559917857534

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN timestamp()

4.2.14. toBoolean()

toBoolean() converts a string value to a boolean value.

Syntax: toBoolean(expression)

Returns:

A Boolean.

Arguments:

Name Description

expression

An expression that returns a boolean or string value.

Considerations:

toBoolean(null) returns null.

If expression is a boolean value, it will be returned unchanged.

If the parsing fails, null will be returned.

Query.  

RETURN toBoolean('TRUE'), toBoolean('not a boolean')

Table 4.20. Result
toBoolean('TRUE') toBoolean('not a boolean')

1 row

true

<null>

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN toBoolean('TRUE'), toBoolean('not a boolean')

4.2.15. toFloat()

toFloat() converts an integer or string value to a floating point number.

Syntax: toFloat(expression)

Returns:

A Float.

Arguments:

Name Description

expression

An expression that returns a numeric or string value.

Considerations:

toFloat(null) returns null.

If expression is a floating point number, it will be returned unchanged.

If the parsing fails, null will be returned.

Query.  

RETURN toFloat('11.5'), toFloat('not a number')

Table 4.21. Result
toFloat('11.5') toFloat('not a number')

1 row

11.5

<null>

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN toFloat('11.5'), toFloat('not a number')

4.2.16. toInteger()

toInteger() converts a floating point or string value to an integer value.

Syntax: toInteger(expression)

Returns:

An Integer.

Arguments:

Name Description

expression

An expression that returns a numeric or string value.

Considerations:

toInteger(null) returns null.

If expression is an integer value, it will be returned unchanged.

If the parsing fails, null will be returned.

Query.  

RETURN toInteger('42'), toInteger('not a number')

Table 4.22. Result
toInteger('42') toInteger('not a number')

1 row

42

<null>

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) RETURN toInteger('42'), toInteger('not a number')

4.2.17. type()

type() returns the string representation of the relationship type.

Syntax: type(relationship)

Returns:

A String.

Arguments:

Name Description

relationship

An expression that returns a relationship.

Considerations:

type(null) returns null.

Query.  

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

The relationship type of r is returned.

Table 4.23. Result
type(r)

2 rows

"KNOWS"

"KNOWS"

Try this query live.  CREATE (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), (bob {name: 'Bob', age: 25, eyes: 'blue'}), (charlie {name: 'Charlie', age: 53, eyes: 'green'}), (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) MATCH (n)-[r]->() WHERE n.name = 'Alice' RETURN type(r)