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()
Syntax |
|
||
Description |
Returns the number of Unicode characters in a |
||
Arguments |
Name |
Type |
Description |
|
|
A string value whose length in characters is to be calculated. |
|
Returns |
|
This function is an alias of the size()
function, and was introduced as part of Cypher®'s GQL conformance.
|
RETURN char_length('Alice')
char_length('Alice') |
---|
|
Rows: 1 |
The number of Unicode characters in the STRING
is returned.
character_length()
Syntax |
|
||
Description |
Returns the number of Unicode characters in a |
||
Arguments |
Name |
Type |
Description |
|
|
A string value whose length in characters is to be calculated. |
|
Returns |
|
This function is an alias of the size()
function, and was introduced as part of Cypher’s GQL conformance.
|
RETURN character_length('Alice')
character_length('Alice') |
---|
|
Rows: 1 |
The number of Unicode characters in the STRING
is returned.
coalesce()
Syntax |
|
||
Description |
Returns the first non-null value in a list of expressions. |
||
Arguments |
Name |
Type |
Description |
|
|
If this is the first non- |
|
Returns |
|
|
MATCH (a)
WHERE a.name = 'Alice'
RETURN coalesce(a.hairColor, a.eyes)
coalesce(a.hairColor, a.eyes) |
---|
|
Rows: 1 |
elementId()
Syntax |
|
||
Description |
Returns the element id of a |
||
Arguments |
Name |
Type |
Description |
|
|
An element id of a node or a relationship. |
|
Returns |
|
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.
|
|
MATCH (n:Developer)
RETURN elementId(n)
The identifier for each Developer
node is returned.
elementId(n) |
---|
|
Rows: 1 |
MATCH (:Developer)-[r]-()
RETURN elementId(r)
The identifier for each relationship connected to a Developer
node is returned.
elementId(r) |
---|
|
|
Rows: 2 |
endNode()
Syntax |
|
||
Description |
Returns the end |
||
Arguments |
Name |
Type |
Description |
|
|
A relationship. |
|
Returns |
|
|
MATCH (x:Developer)-[r]-()
RETURN endNode(r)
endNode(r) |
---|
|
|
Rows: 2 |
head()
Syntax |
|
||
Description |
Returns the first element in a |
||
Arguments |
Name |
Type |
Description |
|
|
A list from which the first element will be returned. |
|
Returns |
|
|
|
If the first element in |
MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.likedColors, head(a.likedColors)
The first element in the list is returned.
a.likedColors+ | +head(a.likedColors) |
---|---|
|
|
Rows: 1 |
id()
It is recommended to use elementId() instead.
|
Syntax |
|
||
Description |
Returns the id of a |
||
Arguments |
Name |
Type |
Description |
|
|
A node or a relationship. |
|
Returns |
|
|
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 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. |
MATCH (a)
RETURN id(a)
The node identifier for each of the nodes is returned.
id(a) |
---|
|
|
|
|
|
Rows: 5 |
last()
Syntax |
|
||
Description |
Returns the last element in a |
||
Arguments |
Name |
Type |
Description |
|
|
A list from which the last element will be returned. |
|
Returns |
|
Considerations:
|
|
If the last element in |
MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.likedColors, last(a.likedColors)
The last element in the list is returned.
a.liked_colors | last(a.liked_colors) |
---|---|
|
|
Rows: 1 |
length()
Syntax |
|
||
Description |
Returns the length of a |
||
Arguments |
Name |
Type |
Description |
|
|
A path whose relationships will be counted. |
|
Returns |
|
|
To calculate the length of a LIST of the number of Unicode characters in a STRING , see size()
|
MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)
The length of the path p
is returned.
length(p) |
---|
|
|
|
Rows: 3 |
nullIf()
Syntax |
|
||
Description |
Returns null if the two given parameters are equivalent, otherwise returns the value of the first parameter. |
||
Arguments |
Name |
Type |
Description |
|
|
A first value to be returned if the second value is not equivalent. |
|
|
|
A second value against which the first value is compared. |
|
Returns |
|
This function is the opposite of the coalesce() function, which returns a default value if the given value is null.
RETURN nullIf(4, 4)
The null value is returned as the two parameters are equivalent.
nullIf(4, 4) |
---|
|
Rows: 1 |
RETURN nullIf("abc", "def")
The first parameter, "abc", is returned, as the two parameters are not equivalent.
nullIf("abc", "def") |
---|
|
Rows: 1 |
The nullIf()
function can be used in conjunction with the coalesce()
function for transforming one data value into another value:
MATCH (a)
RETURN a.name AS name, coalesce(nullIf(a.eyes, "Brown"), "Hazel") AS eyeColor
name | eyeColor |
---|---|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
properties()
Syntax |
|
||
Description |
Returns a |
||
Arguments |
Name |
Type |
Description |
|
|
An entity to return the properties from. |
|
Returns |
|
|
If |
CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)
properties(p) |
---|
|
Rows: 1 |
randomUUID()
Syntax |
|
||
Description |
Generates a random UUID. |
||
Returns |
|
A Universally Unique Identified (UUID), also known as a Globally Unique Identifier (GUID), is a 128-bit value with strong guarantees of uniqueness.
RETURN randomUUID() AS uuid
uuid |
---|
|
Rows: 1 |
A randomly-generated UUID is returned.
size()
Syntax |
|
||
Description |
Returns the number of items in a |
||
Arguments |
Name |
Type |
Description |
|
|
A value whose length is to be calculated. |
|
Returns |
|
To calculate the length of a PATH , see length() .
|
|
RETURN size(['Alice', 'Bob'])
size(['Alice', 'Bob']) |
---|
|
Rows: 1 |
The number of elements in the list is returned.
MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof
fof |
---|
|
Rows: 1 |
The number of paths matching the pattern expression is returned. (The size of the list of paths).
MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)
size(a.name) |
---|
|
Rows: 1 |
The number of characters in the STRING
'Charlie'
is returned.
startNode()
Syntax |
|
||
Description |
Returns the start |
||
Arguments |
Name |
Type |
Description |
|
|
A relationship. |
|
Returns |
|
|
MATCH (x:Developer)-[r]-()
RETURN startNode(r)
startNode(r) |
---|
|
|
Rows: 2 |
timestamp()
Syntax |
|
||
Description |
Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC |
||
Returns |
|
It is the equivalent of |
|
RETURN timestamp()
The time in milliseconds is returned.
timestamp() |
---|
|
Rows: 1 |
toBoolean()
Syntax |
|
||
Description |
Converts a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into a boolean. |
|
Returns |
|
|
If |
If the parsing fails, |
If |
This function will return an error if provided with an expression that is not a |
RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0)
toBoolean('true') | toBoolean('not a boolean') | toBoolean(0) |
---|---|---|
|
|
|
Rows: 1 |
toBooleanOrNull()
Syntax |
|
||
Description |
Converts a value to a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into a boolean or null. |
|
Returns |
|
|
If |
If the parsing fails, |
If |
If the |
RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNull(0), toBooleanOrNull(1.5)
toBooleanOrNull('true') | toBooleanOrNull('not a boolean') | toBooleanOrNull(0) | toBooleanOrNull(1.5) |
---|---|---|---|
|
|
|
|
Rows: 1 |
toFloat()
Syntax |
|
||
Description |
Converts a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into a float. |
|
Returns |
|
|
If |
If the parsing fails, |
This function will return an error if provided with an expression that is not an |
RETURN toFloat('11.5'), toFloat('not a number')
toFloat('11.5') | toFloat('not a number') |
---|---|
|
|
Rows: 1 |
toFloatOrNull()
Syntax |
|
||
Description |
Converts a value to a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into a float or null. |
|
Returns |
|
|
If |
If the parsing fails, |
If the |
RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true)
toFloatOrNull('11.5') | toFloatOrNull('not a number') | toFloatOrNull(true) |
---|---|---|
|
|
|
Rows: 1 |
toInteger()
Syntax |
|
||
Description |
Converts a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into an integer. |
|
Returns |
|
|
If |
If the parsing fails, |
If |
If |
This function will return an error if provided with an expression that is not a |
RETURN toInteger('42'), toInteger('not a number'), toInteger(true)
toInteger('42') | toInteger('not a number') | toInteger(true) |
---|---|---|
|
|
|
Rows: 1 |
toIntegerOrNull()
Syntax |
|
||
Description |
Converts a value to an |
||
Arguments |
Name |
Type |
Description |
|
|
A value to be converted into an integer or null. |
|
Returns |
|
|
If |
If the parsing fails, |
If |
If |
If the |
RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(true), toIntegerOrNull(['A', 'B', 'C'])
toIntegerOrNull('42') | toIntegerOrNull('not a number') | toIntegerOrNull(true) | toIntegerOrNull(['A', 'B', 'C']) |
---|---|---|---|
|
|
|
|
Rows: 1 |
type()
Syntax |
|
||
Description |
Returns a |
||
Arguments |
Name |
Type |
Description |
|
|
A relationship. |
|
Returns |
|
|
MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)
The relationship type of r
is returned.
type(r) |
---|
|
|
Rows: 2 |
valueType()
Syntax |
|
||
Description |
Returns a |
||
Arguments |
Name |
Type |
Description |
|
|
A value to return the type of. |
|
Returns |
|
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.
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 the next major release of Neo4j.
As a result,"FLOAT"
would continue to be returned for any FLOAT32
values until the next major release.
The below list contains all currently supported types displayed by the valueType()
function:
-
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.
UNWIND ["abc", 1, 2.0, true, [date()]] AS value
RETURN valueType(value) AS result
result |
---|
|
|
|
|
|
Rows: 5 |