Scalar functions

The length() and size() functions are quite similar, and so it is important to take note of the difference. Owing to backwards compatibility, length() currently works on four types: strings, paths, lists and pattern expressions. However, it is recommended to use length() only for paths, and the size() function for strings, lists and pattern expressions. length() on those types may be deprecated in future.

The timestamp() function returns the equivalent value of datetime().epochMillis.

The function toInt() has been superseded by toInteger(), and will be removed in a future release.

Functions:

Graph
  N0 [
    label = "{Developer|name = \'Alice\'\leyes = \'brown\'\lage = 38\l}"
  ]
  N0 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N0 -> N1 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N1 [
    label = "name = \'Bob\'\leyes = \'blue\'\lage = 25\l"
  ]
  N1 -> N4 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "MARRIED\n"
  ]
  N1 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N2 [
    label = "name = \'Charlie\'\leyes = \'green\'\lage = 53\l"
  ]
  N2 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "KNOWS\n"
  ]
  N3 [
    label = "name = \'Daniel\'\leyes = \'brown\'\lage = 54\l"
  ]
  N4 [
    label = "array = \[\'one\', \'two\', \'three\'\]\lname = \'Eskil\'\leyes = \'blue\'\lage = 41\l"
  ]

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

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

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

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. For examples on how to get a node and a relationship by ID, see Get node or relationship by id.

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.

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 identifier for each of the nodes is returned.

Table 4. Result
id(a)

0

1

2

3

4

5 rows

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

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

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

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

"401ee4f1-6eb3-45f9-9cd9-c2a2f3a2a7f8"

1 row

A randomly-generated UUID is returned.

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.

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.

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.

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

timestamp()

timestamp() returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

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

1632753553112

1 row

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

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

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

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