Scalar functions

Scalar functions return a single value.

Example graph

The following graph is used for the examples below:

To recreate the graph, run the following query against an empty Neo4j database:

CREATE
  (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}),
  (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}),
  (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}),
  (daniel:Adminstrator {name: 'Daniel', age: 54, eyes: 'Brown'}),
  (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:KNOWS]->(charlie),
  (bob)-[:KNOWS]->(daniel),
  (charlie)-[:KNOWS]->(daniel),
  (bob)-[:MARRIED]->(eskil)

char_length()

Details
Syntax	`char_length(input)`
Description	Returns the number of Unicode characters in a `STRING`.
Arguments	Name	Type	Description
	`input`	`STRING`	A string value whose length in characters is to be calculated.
Returns	`INTEGER`

This function is an alias of the size() function, and was introduced as part of Cypher^®'s GQL conformance.

Considerations
`char_length(null)` returns `null`.

Example 1. char_length()

Query

RETURN char_length('Alice')

Result
char_length('Alice')
`5`
Rows: 1

The number of Unicode characters in the STRING is returned.

character_length()

Details
Syntax	`character_length(input)`
Description	Returns the number of Unicode characters in a `STRING`.
Arguments	Name	Type	Description
	`input`	`STRING`	A string value whose length in characters is to be calculated.
Returns	`INTEGER`

This function is an alias of the size() function, and was introduced as part of Cypher’s GQL conformance.

Considerations
`character_length(null)` returns `null`.

Example 2. character_length()

Query

RETURN character_length('Alice')

Result
character_length('Alice')
`5`
Rows: 1

The number of Unicode characters in the STRING is returned.

coalesce()

Details
Syntax	`coalesce(input)`
Description	Returns the first non-null value in a list of expressions.
Arguments	Name	Type	Description
	`input`	`ANY`	If this is the first non-`NULL` value, it will be returned.
Returns	`ANY`

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)

Result
coalesce(a.hairColor, a.eyes)
`"Brown"`
Rows: 1

elementId()

Details
Syntax	`elementId(input)`
Description	Returns the element id of a `NODE` or `RELATIONSHIP`.
Arguments	Name	Type	Description
	`input`	`NODE \| RELATIONSHIP`	An element id of a node or a relationship.
Returns	`STRING`

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

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.
Neo4j reuses its internal IDs when nodes and relationships are deleted. Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate. It is therefore recommended to use application-generated IDs.

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.

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.

Result
elementId(r)
`"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:0"`
`"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:1"`
Rows: 2

endNode()

Details
Syntax	`endNode(input)`
Description	Returns the end `NODE` of a `RELATIONSHIP`.
Arguments	Name	Type	Description
	`input`	`RELATIONSHIP`	A relationship.
Returns	`NODE`

Considerations
`endNode(null)` returns `null`.

Example 6. endNode()

Query

MATCH (x:Developer)-[r]-()
RETURN endNode(r)

Result
endNode(r)
`{name: "Bob", age: 25, eyes: "Blue"}`
`{name: "Charlie", age: 53, eyes: "Green"}`
Rows: 2

head()

Details
Syntax	`head(list)`
Description	Returns the first element in a `LIST<ANY>`.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list from which the first element will be returned.
Returns	`ANY`

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.likedColors, head(a.likedColors)

The first element in the list is returned.

Result
a.likedColors+	+head(a.likedColors)
`["Pink", "Yellow", "Black"]`	`"Pink"`
Rows: 1

id()

It is recommended to use elementId() instead.

Details
Syntax	`id(input)`
Description	Returns the id of a `NODE` or `RELATIONSHIP`.
Arguments	Name	Type	Description
	`input`	`NODE \| RELATIONSHIP`	A node or a relationship.
Returns	`INTEGER`

Considerations
`id(null)` returns `null`.

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

The function id() returns a node or a relationship identifier, unique by an object type and a database. Therefore, id() can return the same value for both nodes and relationships in the same database.
Neo4j implements the ID so that every node and relationship in a database has an identifier. The identifier for a node or relationship is guaranteed to be unique among other nodes' and relationships' identifiers in the same database, within the scope of a single transaction.
Neo4j reuses its internal IDs when nodes and relationships are deleted. Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate. It is therefore recommended to use application-generated IDs instead.

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.

Example 8. id()

Query

MATCH (a)
RETURN id(a)

The node identifier for each of the nodes is returned.

Result
id(a)
`0`
`1`
`2`
`3`
`4`
Rows: 5

last()

Details
Syntax	`last(list)`
Description	Returns the last element in a `LIST<ANY>`.
Arguments	Name	Type	Description
	`list`	`LIST<ANY>`	A list from which the last element will be returned.
Returns	`ANY`

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.likedColors, last(a.likedColors)

The last element in the list is returned.

Result
a.liked_colors	last(a.liked_colors)
`["Pink", "Yellow", "Black"]`	`"Black"`
Rows: 1

length()

Details
Syntax	`length(input)`
Description	Returns the length of a `PATH`.
Arguments	Name	Type	Description
	`input`	`PATH`	A path whose relationships will be counted.
Returns	`INTEGER`

Considerations
`length(null)` returns `null`.

To calculate the length of a LIST of the number of Unicode characters in a STRING, see size()

Example 10. length()

Query

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)

The length of the path p is returned.

Result
length(p)
`2`
`2`
`2`
Rows: 3

nullIf()

Details
Syntax	`nullIf(v1, v2)`
Description	Returns null if the two given parameters are equivalent, otherwise returns the value of the first parameter.
Arguments	Name	Type	Description
	`v1`	`ANY`	A first value to be returned if the second value is not equivalent.
	`v2`	`ANY`	A second value against which the first value is compared.
Returns	`ANY`

This function is the opposite of the coalesce() function, which returns a default value if the given value is null.

Example 11. nullIf()

Query

RETURN nullIf(4, 4)

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

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.

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

Result
name	eyeColor
`"Alice"`	`"Hazel"`
`"Bob"`	`"Blue"`
`"Charlie"`	`"Green"`
`"Daniel"`	`"Hazel"`
`"Eskil"`	`"Blue"`
Rows: 5

properties()

Details
Syntax	`properties(input)`
Description	Returns a `MAP` containing all the properties of a `NODE`, `RELATIONSHIP` or `MAP`.
Arguments	Name	Type	Description
	`input`	`NODE \| RELATIONSHIP \| MAP`	An entity to return the properties from.
Returns	`MAP`

Considerations
`properties(null)` returns `null`.
If `input` is already a `MAP`, it is returned unchanged.

Example 14. properties()

Query

CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)

Result
properties(p)
`{"city": "Berlin", "name": "Stefan"}`
Rows: 1

randomUUID()

Details
Syntax	`randomUUID()`
Description	Generates a random UUID.
Returns	`STRING`

A Universally Unique Identified (UUID), also known as a Globally Unique Identifier (GUID), is a 128-bit value with strong guarantees of uniqueness.

Example 15. randomUUID()

Query

RETURN randomUUID() AS uuid

Result
uuid
`"9f4c297d-309a-4743-a196-4525b96135c1"`
Rows: 1

A randomly-generated UUID is returned.

size()

Details
Syntax	`size(input)`
Description	Returns the number of items in a `LIST<ANY>` or the number of Unicode characters in a `STRING`.
Arguments	Name	Type	Description
	`input`	`STRING \| LIST<ANY>`	A value whose length is to be calculated.
Returns	`INTEGER`

To calculate the length of a PATH, see length().

Considerations
`size(null)` returns `null`.

Example 16. size() applied to lists

Query

RETURN size(['Alice', 'Bob'])

Result
size(['Alice', 'Bob'])
`2`
Rows: 1

The number of elements in the list is returned.

Example 17. size() applied to pattern comprehensions

Query

MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof

Result
fof
`3`
Rows: 1

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

Example 18. size() applied to strings

Query

MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)

Result
size(a.name)
`7`
Rows: 1

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

startNode()

Details
Syntax	`startNode(input)`
Description	Returns the start `NODE` of a `RELATIONSHIP`.
Arguments	Name	Type	Description
	`input`	`RELATIONSHIP`	A relationship.
Returns	`NODE`

Considerations
`startNode(null)` returns `null`.

Example 19. startNode()

Query

MATCH (x:Developer)-[r]-()
RETURN startNode(r)

Result
startNode(r)
`{name: "Alice", age: 38, eyes: "Brown"}`
`{name: "Alice", age: 38, eyes: "Brown"}`
Rows: 2

timestamp()

Details
Syntax	`timestamp()`
Description	Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
Returns	`INTEGER`

It is the equivalent of datetime().epochMillis.

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.

Result
timestamp()
`1655201331965`
Rows: 1

toBoolean()

Details
Syntax	`toBoolean(input)`
Description	Converts a `BOOLEAN`, `STRING` or `INTEGER` value to a `BOOLEAN` value. For `INTEGER` values, 0 is defined to be false and any other `INTEGER` is defined to be true.
Arguments	Name	Type	Description
	`input`	`BOOLEAN \| STRING \| INTEGER`	A value to be converted into a boolean.
Returns	`BOOLEAN`

Considerations
`toBoolean(null)` returns `null`.
If `input` is a `BOOLEAN` value, it will be returned unchanged.
If the parsing fails, `null` will be returned.
If `input` 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)

Result
toBoolean('true')	toBoolean('not a boolean')	toBoolean(0)
`true`	`<null>`	`false`
Rows: 1

toBooleanOrNull()

Details
Syntax	`toBooleanOrNull(input)`
Description	Converts a value to a `BOOLEAN` value, or null if the value cannot be converted.
Arguments	Name	Type	Description
	`input`	`ANY`	A value to be converted into a boolean or null.
Returns	`BOOLEAN`

Considerations
`toBooleanOrNull(null)` returns `null`.
If `input` is a `BOOLEAN` value, it will be returned unchanged.
If the parsing fails, `null` will be returned.
If `input` is the `INTEGER` value `0`, `false` will be returned. For any other `INTEGER` value `true` will be returned.
If the `input` 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)

Result
toBooleanOrNull('true')	toBooleanOrNull('not a boolean')	toBooleanOrNull(0)	toBooleanOrNull(1.5)
`true`	`<null>`	`false`	`<null>`
Rows: 1

toFloat()

Details
Syntax	`toFloat(input)`
Description	Converts a `STRING`, `INTEGER` or `FLOAT` value to a `FLOAT` value.
Arguments	Name	Type	Description
	`input`	`STRING \| INTEGER \| FLOAT`	A value to be converted into a float.
Returns	`FLOAT`

Considerations
`toFloat(null)` returns `null`.
If `input` 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')

Result
toFloat('11.5')	toFloat('not a number')
`11.5`	`<null>`
Rows: 1

toFloatOrNull()

Details
Syntax	`toFloatOrNull(input)`
Description	Converts a value to a `FLOAT` value, or null if the value cannot be converted.
Arguments	Name	Type	Description
	`input`	`ANY`	A value to be converted into a float or null.
Returns	`FLOAT`

Considerations
`toFloatOrNull(null)` returns `null`.
If `input` is a `FLOAT`, it will be returned unchanged.
If the parsing fails, `null` will be returned.
If the `input` 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)

Result
toFloatOrNull('11.5')	toFloatOrNull('not a number')	toFloatOrNull(true)
`11.5`	`<null>`	`<null>`
Rows: 1

toInteger()

Details
Syntax	`toInteger(input)`
Description	Converts a `BOOLEAN`, `STRING`, `INTEGER` or `FLOAT` value to an `INTEGER` value. For `BOOLEAN` values, true is defined to be 1 and false is defined to be 0.
Arguments	Name	Type	Description
	`input`	`BOOLEAN \| STRING \| INTEGER \| FLOAT`	A value to be converted into an integer.
Returns	`INTEGER`

Considerations
`toInteger(null)` returns `null`.
If `input` is an `INTEGER` value, it will be returned unchanged.
If the parsing fails, `null` will be returned.
If `input` is the boolean value `false`, `0` will be returned.
If `input` 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)

Result
toInteger('42')	toInteger('not a number')	toInteger(true)
`42`	`<null>`	`1`
Rows: 1

toIntegerOrNull()

Details
Syntax	`toIntegerOrNull(input)`
Description	Converts a value to an `INTEGER` value, or null if the value cannot be converted.
Arguments	Name	Type	Description
	`input`	`ANY`	A value to be converted into an integer or null.
Returns	`INTEGER`

Considerations
`toIntegerOrNull(null)` returns `null`.
If `input` is an `INTEGER` value, it will be returned unchanged.
If the parsing fails, `null` will be returned.
If `input` is the `BOOLEAN` value `false`, `0` will be returned.
If `input` is the `BOOLEAN` value `true`, `1` will be returned.
If the `input` 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'])

Result
toIntegerOrNull('42')	toIntegerOrNull('not a number')	toIntegerOrNull(true)	toIntegerOrNull(['A', 'B', 'C'])
`42`	`<null>`	`1`	`<null>`
Rows: 1

type()

Details
Syntax	`type(input)`
Description	Returns a `STRING` representation of the `RELATIONSHIP` type.
Arguments	Name	Type	Description
	`input`	`RELATIONSHIP`	A relationship.
Returns	`STRING`

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.

Result
type(r)
`"KNOWS"`
`"KNOWS"`
Rows: 2

valueType()

Details
Syntax	`valueType(input)`
Description	Returns a `STRING` representation of the most precise value type that the given expression evaluates to.
Arguments	Name	Type	Description
	`input`	`ANY`	A value to return the type of.
Returns	`STRING`

The output is deterministic and makes use of Type Normalization.

Considerations:

Future releases of Cypher may 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

Result
result
`"STRING NOT NULL"`
`"INTEGER NOT NULL"`
`"FLOAT NOT NULL"`
`"BOOLEAN NOT NULL"`
`"LIST<DATE NOT NULL> NOT NULL"`
Rows: 5