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, 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 13.2. Graph

cypher-functions-graph.svg

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

2

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; return size(['Alice', 'Bob']) as col

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

3

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Alice' return size( (a)-->()-->() ) as fof

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match p=(a)-->(b)-->(c) where a.name='Alice' return length(p)

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where length(a.name) > 6 return length(a.name)

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"

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (n)-[r]->() where n.name='Alice' return type(r)

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) return id(a)

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"

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Alice' return coalesce(a.hairColor, a.eyes)

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.arrayhead(a.array)
1 row

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

"one"

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Eskil' return a.array, head(a.array)

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.arraylast(a.array)
1 row

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

"three"

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; match (a) where a.name='Eskil' return a.array, last(a.array)

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

1465371248941

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; return timestamp()

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[0]{name:"Alice",age:38,eyes:"brown"}

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; MATCH (x:foo)-[r]-() return startNode(r)

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[2]{name:"Charlie",age:53,eyes:"green"}

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

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; MATCH (x:foo)-[r]-() return endNode(r)

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)
1 row
Nodes created: 1
Properties set: 2
Labels added: 1

{name -> "Stefan", city -> "Berlin"}

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; create (p:Person {name: 'Stefan', city: 'Berlin'}) return properties(p)

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>

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; return toInt("42"), toInt("not a number")

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>

Try this query live create (_0:`bar`:`foo` {`age`:38, `eyes`:"brown", `name`:"Alice"}) create (_1 {`age`:25, `eyes`:"blue", `name`:"Bob"}) create (_2 {`age`:53, `eyes`:"green", `name`:"Charlie"}) create (_3 {`age`:54, `eyes`:"brown", `name`:"Daniel"}) create (_4:`Spouse` {`age`:41, `array`:["one", "two", "three"], `eyes`:"blue", `name`:"Eskil"}) create (_0)-[:`KNOWS`]->(_2) create (_0)-[:`KNOWS`]->(_1) create (_1)-[:`MARRIED`]->(_4) create (_1)-[:`KNOWS`]->(_3) create (_2)-[:`KNOWS`]->(_3) ; return toFloat("11.5"), toFloat("not a number")