13.2. Scalar functions

Scalar functions return a single value.

[Important]Important

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, collections and pattern expressions. However, for clarity it is recommended to only use LENGTH on strings and paths, and use the new SIZE function on collections and pattern expressions. LENGTH on those types may be deprecated in future.

Figure 13.2. Graph

SIZE

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

Syntax: SIZE( collection )

Arguments:

  • collection: An expression that returns a collection

Query 

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

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

Result

col
1 row

2

SIZE of pattern expression

This is the same SIZE() method described before, but instead of passing in a collection 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 collection

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
1 row

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)
3 rows

2

2

2

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)
1 row

7

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)
2 rows

"KNOWS"

"KNOWS"

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)
5 rows

0

1

2

3

4

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)
1 row

"brown"

HEAD

HEAD returns the first element in a collection.

Syntax: HEAD( expression )

Arguments:

  • expression: This expression should return a collection 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.arrayhead(a.array)
1 row

["one","two","three"]

"one"

LAST

LAST returns the last element in a collection.

Syntax: LAST( expression )

Arguments:

  • expression: This expression should return a collection 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.arraylast(a.array)
1 row

["one","two","three"]

"three"

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

1440908540323

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)
2 rows

Node[2]{name:"Alice",age:38,eyes:"brown"}

Node[2]{name:"Alice",age:38,eyes:"brown"}

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)
2 rows

Node[4]{name:"Charlie",age:53,eyes:"green"}

Node[3]{name:"Bob",age:25,eyes:"blue"}

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")
1 row

42

<null>

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")
1 row

11.5

<null>