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.

Function length()

Only works for paths.

Function size()

Only works for the three types: strings, lists, pattern comprehension.

graph scalar functions

coalesce()

The function 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 that may return null.

Considerations:

null will be returned if all the arguments are null.
Example 1. coalesce()
Query
MATCH (a)
WHERE a.name = 'Alice'
RETURN coalesce(a.hairColor, a.eyes)
Table 1. Result
coalesce(a.hairColor, a.eyes)

"brown"

Rows: 1

elementId()

The function elementId() returns a node or relationship identifier, unique within a specific transaction and DBMS.

There are important considerations to bear in mind when using elementId():

  1. Every node and relationship is guaranteed an element ID. This ID is unique among both nodes and relationships across all databases in the same DBMS within the scope of a single transaction. However, no guarantees are given regarding the order of the returned ID values or the length of the ID string values. Outside of the scope of a single transaction, no guarantees are given about the mapping between ID values and elements.

  2. Neo4j reuses its internal IDs when nodes and relationships are deleted. This means that applications using, and relying on internal Neo4j IDs, are brittle or at risk of making mistakes. It is therefore recommended to rather use application-generated IDs.

Syntax:

elementId(expression)

Returns:

A String.

Arguments:

Name Description

expression

An expression that returns a node or a relationship.

Considerations:

elementId(null) returns null.

elementId on values other than a node, relationship, or null will fail the query.
Example 2. elementId()
Query
MATCH (a)
RETURN elementId(a)

The node identifier for each of the nodes is returned.

Table 2. Result
elementId(a)

"4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0"

"4:c0a65d96-4993-4b0c-b036-e7ebd9174905:1"

"4:c0a65d96-4993-4b0c-b036-e7ebd9174905:2"

"4:c0a65d96-4993-4b0c-b036-e7ebd9174905:3"

"4:c0a65d96-4993-4b0c-b036-e7ebd9174905:4"

Rows: 5

endNode()

The function 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.
Example 3. endNode()
Query
MATCH (x:Developer)-[r]-()
RETURN endNode(r)
Table 3. Result
endNode(r)

{name:"Bob",age:25,eyes:"blue"}

{name:"Charlie",age:53,eyes:"green"}

Rows: 2

head()

The function head() returns the first element in a list.

Syntax:

head(expression)

Returns:

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

Arguments:

Name Description

expression

An expression that returns a list.

Considerations:

head(null) returns null.

head([]) returns null.

If the first element in list is null, head(list) will return null.
Example 4. head()
Query
MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.liked_colors, head(a.liked_colors)

The first element in the list is returned.

Table 4. Result
a.liked_colors head(a.liked_colors)

["pink","yellow","black"]

"pink"

Rows: 1

id() Deprecated

The function id() returns a node or a relationship identifier, unique by an object type and a database. Therefore, it is perfectly allowable for id() to return the same value for both nodes and relationships in the same database. For examples on how to get a node and a relationship by ID, see Get node or relationship by ID.

The function id is deprecated. Use the function elementId instead.

Neo4j implements the ID so that:

Node

Every node in a database has an identifier. The identifier for a node is guaranteed to be unique among other nodes' identifiers in the same database, within the scope of a single transaction.

Relationship

Every relationship in a database has an identifier. The identifier for a relationship is guaranteed to be unique among other relationships' identifiers in the same database, within the scope of a single transaction.

On a composite database, the id() function should be used with caution. It is recommended to use elementId() instead.

When called in database-specific subqueries, the resulting id value for a node or relationship is local to that database. The local id for nodes or relationships from different databases may be the same.

When called from the root context of a query, the resulting value is an extended id for the node or relationship. The extended id is likely different from the local id for the same node or relationship.

Syntax:

id(expression)

Returns:

An Integer.

Arguments:

Name Description

expression

An expression that returns a node or a relationship.

Considerations:

id(null) returns null.
Example 5. id()
Query
MATCH (a)
RETURN id(a)

The node identifier for each of the nodes is returned.

Table 5. Result
id(a)

0

1

2

3

4

Rows: 5

last()

The function 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 the list.

Arguments:

Name Description

expression

An expression that returns a list.

Considerations:

last(null) returns null.

last([]) returns null.

If the last element in list is null, last(list) will return null.
Example 6. last()
Query
MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.liked_colors, last(a.liked_colors)

The last element in the list is returned.

Table 6. Result
a.liked_colors last(a.liked_colors)

["pink","yellow","black"]

"black"

Rows: 1

length()

The function 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.
Example 7. length()
Query
MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)

The length of the path p is returned.

Table 7. Result
length(p)

2

2

2

Rows: 3

properties()

The function properties() returns a map containing all the properties; the function can be utilized for a relationship or a node. 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 relationship, a node, or a map.

Considerations:

properties(null) returns null.
Example 8. properties()
Query
CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)
Table 8. Result
properties(p)

{"city":"Berlin","name":"Stefan"}

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

randomUUID()

The function 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.
Example 9. randomUUID()
Query
RETURN randomUUID() AS uuid
Table 9. Result
uuid

"9f4c297d-309a-4743-a196-4525b96135c1"

Rows: 1

A randomly-generated UUID is returned.

size()

The function 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.
Example 10. size()
Query
RETURN size(['Alice', 'Bob'])
Table 10. Result
size(['Alice', 'Bob'])

2

Rows: 1

The number of elements in the list is returned.

size() applied to pattern comprehension

This is the same function size() as described above, but you pass in a pattern comprehension. The function size will then calculate on a list of paths.

Syntax:

size(pattern comprehension)

Arguments:

Name Description

pattern comprehension

A pattern comprehension that returns a list.
Example 11. size()
Query
MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof
Table 11. Result
fof

3

Rows: 1

The number of paths matching the pattern expression is returned. (The size of the list of paths).

size() applied to string

The function 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.
Example 12. size()
Query
MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)
Table 12. Result
size(a.name)

7

Rows: 1

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

startNode()

The function 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.
Example 13. startNode()
Query
MATCH (x:Developer)-[r]-()
RETURN startNode(r)
Table 13. Result
startNode(r)

{name:"Alice",age:38,eyes:"brown"}

{name:"Alice",age:38,eyes:"brown"}

Rows: 2

timestamp()

The function 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.
Example 14. timestamp()
Query
RETURN timestamp()

The time in milliseconds is returned.

Table 14. Result
timestamp()

1655201331965

Rows: 1

toBoolean()

The function toBoolean() converts a string, integer or boolean value to a boolean value.

Syntax:

toBoolean(expression)

Returns:

A Boolean.

Arguments:

Name Description

expression

An expression that returns a boolean, string or integer 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.

If expression is the integer value 0, false will be returned. For any other integer value true will be returned.

This function will return an error if provided with an expression that is not a string, integer or boolean value.
Example 15. toBoolean()
Query
RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0)
Table 15. Result
toBoolean('true') toBoolean('not a boolean') toBoolean(0)

true

<null>

false

Rows: 1

toBooleanOrNull()

The function toBooleanOrNull() converts a string, integer or boolean value to a boolean value. For any other input value, null will be returned.

Syntax:

toBooleanOrNull(expression)

Returns:

A Boolean or null.

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

toBooleanOrNull(null) returns null.

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

If the parsing fails, null will be returned.

If expression is the integer value 0, false will be returned. For any other integer value true will be returned.

If the expression is not a string, integer or boolean value, null will be returned.
Example 16. toBooleanOrNull()
Query
RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNull(0), toBooleanOrNull(1.5)
Table 16. Result
toBooleanOrNull('true') toBooleanOrNull('not a boolean') toBooleanOrNull(0) toBooleanOrNull(1.5)

true

<null>

false

<null>

Rows: 1

toFloat()

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

Syntax:

toFloat(expression)

Returns:

A Float.

Arguments:

Name Description

expression

An expression that returns a numeric or a 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.

This function will return an error if provided with an expression that is not an integer, floating point or a string value.
Example 17. toFloat()
Query
RETURN toFloat('11.5'), toFloat('not a number')
Table 17. Result
toFloat('11.5') toFloat('not a number')

11.5

<null>

Rows: 1

toFloatOrNull()

The function toFloatOrNull() converts an integer, floating point or a string value to a floating point number. For any other input value, null will be returned.

Syntax:

toFloatOrNull(expression)

Returns:

A Float or null.

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

toFloatOrNull(null) returns null.

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

If the parsing fails, null will be returned.

If the expression is not an integer, floating point or a string value, null will be returned.
Example 18. toFloatOrNull()
Query
RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true)
Table 18. Result
toFloatOrNull('11.5') toFloatOrNull('not a number') toFloatOrNull(true)

11.5

<null>

<null>

Rows: 1

toInteger()

The function toInteger() converts a boolean, integer, floating point or a string value to an integer value.

Syntax:

toInteger(expression)

Returns:

An Integer.

Arguments:

Name Description

expression

An expression that returns a boolean, numeric or a 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.

If expression is the boolean value false, 0 will be returned.

If expression is the boolean value true, 1 will be returned.

This function will return an error if provided with an expression that is not a boolean, floating point, integer or a string value.
Example 19. toInteger()
Query
RETURN toInteger('42'), toInteger('not a number'), toInteger(true)
Table 19. Result
toInteger('42') toInteger('not a number') toInteger(true)

42

<null>

1

Rows: 1

toIntegerOrNull()

The function toIntegerOrNull() converts a boolean, integer, floating point or a string value to an integer value. For any other input value, null will be returned.

Syntax:

toIntegerOrNull(expression)

Returns:

An Integer or null.

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

toIntegerOrNull(null) returns null.

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

If the parsing fails, null will be returned.

If expression is the boolean value false, 0 will be returned.

If expression is the boolean value true, 1 will be returned.

If the expression is not a boolean, floating point, integer or a string value, null will be returned.
Example 20. toIntegerOrNull()
Query
RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(true), toIntegerOrNull(['A', 'B', 'C'])
Table 20. Result
toIntegerOrNull('42') toIntegerOrNull('not a number') toIntegerOrNull(true) toIntegerOrNull(['A', 'B', 'C'])

42

<null>

1

<null>

Rows: 1

type()

The function 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.
Example 21. type()
Query
MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)

The relationship type of r is returned.

Table 21. Result
type(r)

"KNOWS"

"KNOWS"

Rows: 2