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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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( property-container )

Arguments:

  • property-container: 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:

  • 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:

  • 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:

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

Arguments:

Query. 

RETURN timestamp()

The time in milliseconds is returned.

Result. 

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

3.4.2.11. startNode()

startNode() returns the starting node of a relationship

Syntax: startNode( relationship )

Arguments:

  • 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:

  • 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 argument 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:

  • 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:

  • 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:

  • 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