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: STRING values, lists, pattern comprehension.

graph scalar functions

char_length()

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()

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() for nodes
Query
MATCH (n:Developer)
RETURN elementId(n)

The identifier for each Developer node is returned.

Table 4. Result
elementId(n)

"4:d8d172ec-96d8-4364-8f5d-9353d776aeb3:0"

Rows: 1

Example 5. elementId() for relationships
Query
MATCH (:Developer)-[r]-()
RETURN elementId(r)

The identifier for each relationship connected to a Developer node is returned.

Table 5. Result
elementId(r)

"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:0"

"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:1"

Rows: 2

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 6. endNode()
Query
MATCH (x:Developer)-[r]-()
RETURN endNode(r)
Table 6. 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 7. 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 7. Result
a.liked_colors head(a.liked_colors)

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

"pink"

Rows: 1

id()

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 8. id()
Query
MATCH (a)
RETURN id(a)

The node identifier for each of the nodes is returned.

Table 8. 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 9. 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 9. 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 10. length()
Query
MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)

The length of the path p is returned.

Table 10. 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. This function is the opposite of the coalesce() function, which returns a default value if the given value is null.

Syntax:

nullIf(v1, v2)

Returns:

ANY

Arguments:

Name Description

v1

An expression that returns ANY.

v2

An expression that returns ANY.

Example 11. nullIf()
Query
RETURN nullIf(4, 4)

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

Table 11. Result
nullIf(4, 4)

null

Rows: 1

Example 12. nullIf()
Query
RETURN nullIf("abc", "def")

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

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

"abc"

Rows: 1

Example 13. nullIf()

The nullIf() function can be used in conjunction with the coalesce() function for transforming one data value into another value:

Query
MATCH (a)
RETURN a.name AS name, coalesce(nullIf(a.eyes, "brown"), "hazel") AS eyeColor
Table 13. Result
name eyeColor

"Alice"

"hazel"

"Bob"

"blue"

"Charlie"

"green"

"Daniel"

"hazel"

"Eskil"

"blue"

Rows: 5

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 14. properties()
Query
CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)
Table 14. 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 15. randomUUID()
Query
RETURN randomUUID() AS uuid
Table 15. 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 16. size()
Query
RETURN size(['Alice', 'Bob'])
Table 16. 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 17. size()
Query
MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof
Table 17. 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 18. size()
Query
MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)
Table 18. 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 19. startNode()
Query
MATCH (x:Developer)-[r]-()
RETURN startNode(r)
Table 19. 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 20. timestamp()
Query
RETURN timestamp()

The time in milliseconds is returned.

Table 20. 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 21. toBoolean()
Query
RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0)
Table 21. 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 22. toBooleanOrNull()
Query
RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNull(0), toBooleanOrNull(1.5)
Table 22. 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 23. toFloat()
Query
RETURN toFloat('11.5'), toFloat('not a number')
Table 23. 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 24. toFloatOrNull()
Query
RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true)
Table 24. 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, FLOAT, INTEGER or a STRING value.

Example 25. toInteger()
Query
RETURN toInteger('42'), toInteger('not a number'), toInteger(true)
Table 25. 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 26. toIntegerOrNull()
Query
RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(true), toIntegerOrNull(['A', 'B', 'C'])
Table 26. 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 27. type()
Query
MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)

The relationship type of r is returned.

Table 27. Result
type(r)

"KNOWS"

"KNOWS"

Rows: 2

valueType()

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 28. valueType()
Query
UNWIND ["abc", 1, 2.0, true, [date()]] AS value
RETURN valueType(value) AS result
Table 28. Result
result

"STRING NOT NULL"

"INTEGER NOT NULL"

"FLOAT NOT NULL"

"BOOLEAN NOT NULL"

"LIST<DATE NOT NULL> NOT NULL"

Rows: 5