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

char_length()

This feature was introduced in Neo4j 5.13.

The function char_length() returns the number of Unicode characters in a STRING. This function is an alias of the size() function.

Syntax:

char_length(string)

Returns:

INTEGER

Arguments:

Name Description

string

An expression that returns a STRING.

Considerations:

char_length(null) returns null.
Example 1. char_length()
Query
RETURN char_length('Alice')
Table 1. Result
char_length('Alice')

5

Rows: 1

The number of Unicode characters in the string is returned.

character_length()

This feature was introduced in Neo4j 5.13.

The function character_length() returns the number of Unicode characters in a STRING. This function is an alias of the size() function.

Syntax:

character_length(string)

Returns:

INTEGER

Arguments:

Name Description

string

An expression that returns a STRING.

Considerations:

character_length(null) returns null.
Example 2. character_length()
Query
RETURN character_length('Alice')
Table 2. Result
character_length('Alice')

5

Rows: 1

The number of Unicode characters in the string is returned.

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 3. coalesce()
Query
MATCH (a)
WHERE a.name = 'Alice'
RETURN coalesce(a.hairColor, a.eyes)
Table 3. 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:

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 4. elementId()
Query
MATCH (a)
RETURN elementId(a)

The node identifier for each of the nodes is returned.

Table 4. 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:

NODE

Arguments:

Name Description

relationship

An expression that returns a RELATIONSHIP.

Considerations:

endNode(null) returns null.
Example 5. endNode()
Query
MATCH (x:Developer)-[r]-()
RETURN endNode(r)
Table 5. 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 6. 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 6. 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.

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:

INTEGER

Arguments:

Name Description

expression

An expression that returns a NODE or a RELATIONSHIP.

Considerations:

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

The node identifier for each of the nodes is returned.

Table 7. 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 8. 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 8. 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:

INTEGER

Arguments:

Name Description

path

An expression that returns a PATH.

Considerations:

length(null) returns null.
Example 9. length()
Query
MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)

The length of the path p is returned.

Table 9. Result
length(p)

2

2

2

Rows: 3

nullIf()

The function nullIf() returns null if the two given parameters are equivalent, otherwise returns the value of the first parameter.

Syntax:

nullIf(v1, v2)

Returns:

ANY

Arguments:

Name Description

v1

An expression that returns ANY.

v2

An expression that returns ANY.
Example 10. nullIf()
Query
RETURN nullIf(4, 4)

The null value is returned as the two parameters are equivalent.

Table 10. Result
nullIf(4, 4)

null

Rows: 1
Example 11. nullIf()
Query
RETURN nullIf("abc", "def")

The first parameter, "abc", is returned, as the two parameters are not equivalent.

Table 11. Result
nullIf("abc", "def")

"abc"

Rows: 1

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:

MAP

Arguments:

Name Description

expression

An expression that returns a RELATIONSHIP, a NODE, or a MAP.

Considerations:

properties(null) returns null.
Example 12. properties()
Query
CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)
Table 12. 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:

STRING
Example 13. randomUUID()
Query
RETURN randomUUID() AS uuid
Table 13. 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:

INTEGER

Arguments:

Name Description

list

An expression that returns a list.

Considerations:

size(null) returns null.
Example 14. size()
Query
RETURN size(['Alice', 'Bob'])
Table 14. 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<PATH>.

Syntax:

size(pattern comprehension)

Arguments:

Name Description

pattern comprehension

A pattern comprehension that returns a list.
Example 15. size()
Query
MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof
Table 15. 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:

INTEGER

Arguments:

Name Description

string

An expression that returns a STRING value.

Considerations:

size(null) returns null.
Example 16. size()
Query
MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)
Table 16. 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:

NODE

Arguments:

Name Description

relationship

An expression that returns a RELATIONSHIP.

Considerations:

startNode(null) returns null.
Example 17. startNode()
Query
MATCH (x:Developer)-[r]-()
RETURN startNode(r)
Table 17. 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:

INTEGER

Considerations:

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

The time in milliseconds is returned.

Table 18. Result
timestamp()

1655201331965

Rows: 1

toBoolean()

The function toBoolean() converts a STRING, INTEGER or BOOLEAN value to a BOOLEAN value.

Syntax:

toBoolean(expression)

Returns:

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 19. toBoolean()
Query
RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0)
Table 19. 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:

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 20. toBooleanOrNull()
Query
RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNull(0), toBooleanOrNull(1.5)
Table 20. 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, FLOAT or a STRING value to a FLOAT.

Syntax:

toFloat(expression)

Returns:

FLOAT

Arguments:

Name Description

expression

An expression that returns an INTEGER, FLOAT or a STRING value.

Considerations:

toFloat(null) returns null.

If expression is a FLOAT, 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, FLOAT or a STRING value.
Example 21. toFloat()
Query
RETURN toFloat('11.5'), toFloat('not a number')
Table 21. Result
toFloat('11.5') toFloat('not a number')

11.5

<null>

Rows: 1

toFloatOrNull()

The function toFloatOrNull() converts an INTEGER, FLOAT or a STRING value to a FLOAT. For any other input value, null will be returned.

Syntax:

toFloatOrNull(expression)

Returns:

FLOAT or null.

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

toFloatOrNull(null) returns null.

If expression is a FLOAT, it will be returned unchanged.

If the parsing fails, null will be returned.

If the expression is not an INTEGER, FLOAT or a STRING value, null will be returned.
Example 22. toFloatOrNull()
Query
RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true)
Table 22. Result
toFloatOrNull('11.5') toFloatOrNull('not a number') toFloatOrNull(true)

11.5

<null>

<null>

Rows: 1

toInteger()

The function toInteger() converts a BOOLEAN, INTEGER, FLOAT or a STRING value to an INTEGER value.

Syntax:

toInteger(expression)

Returns:

INTEGER

Arguments:

Name Description

expression

An expression that returns a BOOLEAN, FLOAT, INTEGER 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 23. toInteger()
Query
RETURN toInteger('42'), toInteger('not a number'), toInteger(true)
Table 23. Result
toInteger('42') toInteger('not a number') toInteger(true)

42

<null>

1

Rows: 1

toIntegerOrNull()

The function toIntegerOrNull() converts a BOOLEAN, INTEGER, FLOAT or a STRING value to an INTEGER value. For any other input value, null will be returned.

Syntax:

toIntegerOrNull(expression)

Returns:

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, FLOAT, INTEGER or a STRING value, null will be returned.
Example 24. toIntegerOrNull()
Query
RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(true), toIntegerOrNull(['A', 'B', 'C'])
Table 24. 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:

STRING

Arguments:

Name Description

relationship

An expression that returns a RELATIONSHIP.

Considerations:

type(null) returns null.
Example 25. type()
Query
MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)

The relationship type of r is returned.

Table 25. Result
type(r)

"KNOWS"

"KNOWS"

Rows: 2

valueType()

This feature was introduced in Neo4j 5.13.

The function valueType() returns a STRING representation of the most precise value type that the given expression evaluates to. The output is deterministic and makes use of Type Normalization.

Syntax:

valueType(expression)

Returns:

STRING

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

It is possible that future releases of Cypher® will include updates to the current type system. This can include the introduction of new types and subtypes of already supported types. If a new type is introduced, it will be returned by the valueType() function as soon as it is released. However, if a more precise subtype of a previously supported type is introduced, it would be considered a breaking change. As a result, any new subtypes introduced after the release of Neo4j 5.13 will not be returned by the valueType() function until the following major release (Neo4j 6.0).

For example, the function currently returns "FLOAT", but if a more specific FLOAT type was added, e.g. FLOAT32, this would be considered more specific and not be returned until Neo4j 6.0. As a result,"FLOAT" would continue to be returned for any FLOAT32 values until the release of Neo4j 6.0.

With this in mind, the below list contains all supported types (as of Neo4j 5.13) displayed by the valueType() function until the release of Neo4j 6.0:

  • Predefined types

    • NOTHING

    • NULL

    • BOOLEAN

    • STRING

    • INTEGER

    • FLOAT

    • DATE

    • LOCAL TIME

    • ZONED TIME

    • LOCAL DATETIME

    • ZONED DATETIME

    • DURATION

    • POINT

    • NODE

    • RELATIONSHIP

  • Constructed types

    • MAP

    • LIST<INNER_TYPE> (ordered by the inner type)

    • PATH

  • Dynamic union types

    • INNER_TYPE_1 \| INNER_TYPE_2…​ (ordered by specific rules for closed dynamic union type)

    • ANY

This should be taken into account when relying on the output of the valueType() function.

See the type predicate expression for an alternative way of testing type values.

Example 26. valueType()
Query
UNWIND ["abc", 1, 2.0, true, [date()]] AS value
RETURN valueType(value) AS result
Table 26. Result
result

"STRING NOT NULL"

"INTEGER NOT NULL"

"FLOAT NOT NULL"

"BOOLEAN NOT NULL"

"LIST<DATE NOT NULL> NOT NULL"

Rows: 5