4.2. Scalar functions - Chapter 4. Functions

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
`"6499d529-843e-4f01-9a75-b3053a126e17"`

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. 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 4.19. Result
timestamp()
1 row
`1580377692232`

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)