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. length() only works for paths, while size() only works for the three types: strings, lists and pattern expressions.

Functions:

Diagram

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 1. Result
coalesce(a.hairColor, a.eyes)

"brown"

1 row

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 2. Result
endNode(r)

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

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

2 rows

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 3. Result
a.array head(a.array)

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

"one"

1 row

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. Result
id(a)

0

1

2

3

4

5 rows

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 5. Result
a.array last(a.array)

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

"three"

1 row

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 6. Result
length(p)

2

2

2

3 rows

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 7. Result
properties(p)

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

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

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 8. Result
uuid

"8179ea17-e8c4-4333-b3cd-5e2c19a57441"

1 row

A randomly-generated UUID is returned.

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 9. Result
size(['Alice', 'Bob'])

2

1 row

The number of elements in the list is returned.

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 10. Result
fof

3

1 row

The number of paths matching the pattern expression is returned.

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 11. Result
size(a.name)

7

1 row

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

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 12. Result
startNode(r)

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

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

2 rows

13. timestamp()

timestamp() returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. It is the equivalent of datetime().epochMillis.

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 13. Result
timestamp()

1610121303081

1 row

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 14. Result
toBoolean('TRUE') toBoolean('not a boolean')

true

<null>

1 row

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 15. Result
toFloat('11.5') toFloat('not a number')

11.5

<null>

1 row

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 16. Result
toInteger('42') toInteger('not a number')

42

<null>

1 row

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 17. Result
type(r)

"KNOWS"

"KNOWS"

2 rows