3.4.2. 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. Due to backwards compatibility, length() currently works on four types: strings, paths, lists and pattern expressions. However, for clarity it is recommended to only use length() on strings and paths, and use the new size() function on lists and pattern expressions. length() on those types may be deprecated in future.

Figure 3.18. Graph
alt

3.4.2.1. size()

To return or filter on the size of a list, use the size() function.

Syntax: size( list )

Arguments:

Name Description

list

An expression that returns a list

Query. 

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

The number of items in the list is returned by the query.

Result. 

+-----+
| col |
+-----+
| 2   |
+-----+
1 row

3.4.2.2. Size of pattern expression

This is the same size() method described before, but instead of passing in a list directly, you provide a pattern expression that can be used in a match query to provide a new set of results. 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

The number of sub-graphs matching the pattern expression is returned by the query.

Result. 

+-----+
| fof |
+-----+
| 3   |
+-----+
1 row

3.4.2.3. length()

To return or filter on the length of a path, use the length() function.

Syntax: length( path )

Arguments:

Name Description

path

An expression that returns a path

Query. 

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

The length of the path p is returned by the query.

Result. 

+-----------+
| length(p) |
+-----------+
| 2         |
| 2         |
| 2         |
+-----------+
3 rows

3.4.2.4. Length of string

To return or filter on the length of a string, use the length() function.

Syntax: length( string )

Arguments:

Name Description

string

An expression that returns a string

Query. 

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

The length of the name 'Charlie' is returned by the query.

Result. 

+----------------+
| length(a.name) |
+----------------+
| 7              |
+----------------+
1 row

3.4.2.5. type()

Returns a string representation of the relationship type.

Syntax: type( relationship )

Arguments:

Name Description

relationship

A relationship.

Query. 

MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)

The relationship type of r is returned by the query.

Result. 

+---------+
| type(r) |
+---------+
| "KNOWS" |
| "KNOWS" |
+---------+
2 rows

3.4.2.6. id()

Returns the id of the relationship or node.

Syntax: id( expression )

Arguments:

Name Description

expression

An expression that returns a node or a relationship.

Query. 

MATCH (a)
RETURN id(a)

This returns the node id for three nodes.

Result. 

+-------+
| id(a) |
+-------+
| 0     |
| 1     |
| 2     |
| 3     |
| 4     |
+-------+
5 rows

3.4.2.7. coalesce()

Returns the first non-null value in the list of expressions passed to it. In case all arguments are null, null will be returned.

Syntax: coalesce( expression [, expression]* )

Arguments:

Name Description

expression

The expression that might return null.

Query. 

MATCH (a)
WHERE a.name = 'Alice'
RETURN coalesce(a.hairColor, a.eyes)

Result. 

+-------------------------------+
| coalesce(a.hairColor, a.eyes) |
+-------------------------------+
| "brown"                       |
+-------------------------------+
1 row

3.4.2.8. head()

head() returns the first element in a list.

Syntax: head( expression )

Arguments:

Name Description

expression

This expression should return a list of some kind.

Query. 

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.array, head(a.array)

The first node in the path is returned.

Result. 

+---------------------------------------+
| a.array               | head(a.array) |
+---------------------------------------+
| ["one","two","three"] | "one"         |
+---------------------------------------+
1 row

3.4.2.9. last()

last() returns the last element in a list.

Syntax: last( expression )

Arguments:

Name Description

expression

This expression should return a list of some kind.

Query. 

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.array, last(a.array)

The last node in the path is returned.

Result. 

+---------------------------------------+
| a.array               | last(a.array) |
+---------------------------------------+
| ["one","two","three"] | "three"       |
+---------------------------------------+
1 row

3.4.2.10. timestamp()

timestamp() returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. It will return the same value during the whole one query, even if the query is a long running one.

Syntax: timestamp()

Query. 

RETURN timestamp()

The time in milliseconds is returned.

Result. 

+---------------+
| timestamp()   |
+---------------+
| 1489188684803 |
+---------------+
1 row

3.4.2.11. startNode()

startNode() returns the starting node of a relationship

Syntax: startNode( relationship )

Arguments:

Name Description

relationship

An expression that returns a relationship

Query. 

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

Result. 

+-------------------------------------------+
| startNode(r)                              |
+-------------------------------------------+
| Node[0]{name:"Alice",age:38,eyes:"brown"} |
| Node[0]{name:"Alice",age:38,eyes:"brown"} |
+-------------------------------------------+
2 rows

3.4.2.12. endNode()

endNode() returns the end node of a relationship

Syntax: endNode( relationship )

Arguments:

Name Description

relationship

An expression that returns a relationship

Query. 

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

Result. 

+---------------------------------------------+
| endNode(r)                                  |
+---------------------------------------------+
| Node[2]{name:"Charlie",age:53,eyes:"green"} |
| Node[1]{name:"Bob",age:25,eyes:"blue"}      |
+---------------------------------------------+
2 rows

3.4.2.13. properties()

properties() converts the arguments to a map of its properties. If the argument is a node or a relationship, the returned map is a map of its properties. If the argument is already a map, it is returned unchanged.

Syntax: properties( expression )

Arguments:

Name Description

expression

An expression that returns a node, a relationship, or a map

Query. 

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

Result. 

+--------------------------------------+
| properties(p)                        |
+--------------------------------------+
| {name -> "Stefan", city -> "Berlin"} |
+--------------------------------------+
1 row
Nodes created: 1
Properties set: 2
Labels added: 1

3.4.2.14. toInt()

toInt() converts the argument to an integer. A string is parsed as if it was an integer number. If the parsing fails, null will be returned. A floating point number will be cast into an integer.

Syntax: toInt( expression )

Arguments:

Name Description

expression

An expression that returns anything

Query. 

RETURN toInt('42'), toInt('not a number')

Result. 

+-------------------------------------+
| toInt('42') | toInt('not a number') |
+-------------------------------------+
| 42          | <null>                |
+-------------------------------------+
1 row

3.4.2.15. toFloat()

toFloat() converts the argument to a float. A string is parsed as if it was an floating point number. If the parsing fails, null will be returned. An integer will be cast to a floating point number.

Syntax: toFloat( expression )

Arguments:

Name Description

expression

An expression that returns anything

Query. 

RETURN toFloat('11.5'), toFloat('not a number')

Result. 

+-------------------------------------------+
| toFloat('11.5') | toFloat('not a number') |
+-------------------------------------------+
| 11.5            | <null>                  |
+-------------------------------------------+
1 row