Prev |  | Next

## 15.23. Functions

Most functions in Cypher will return `null` if the input parameter is `null`.

Here is a list of the functions in Cypher, seperated into three different sections: Predicates, Scalar functions and Aggregated functions

Figure 15.11. Graph

### 15.23.1. Predicates

Predicates are boolean functions that return true or false for a given set of input. They are most commonly used to filter out subgraphs in the `WHERE` part of a query.

#### ALL

Tests whether a predicate holds for all element of this collection collection.

Syntax: `ALL(identifier in collection WHERE predicate)`

Arguments:

- collection: An expression that returns a collection
- identifier: This is the identifier that can be used from the predicate.
- predicate: A predicate that is tested against all items in the collection.

Query.

    START a=node(3), b=node(1)
    MATCH p=a-[*1..3]->b
    WHERE all(x in nodes(p)
    WHERE x.age > 30)
    RETURN p

All nodes in the returned paths will have an `age` property of at least 30.

Result

p
1 row
1 ms
`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"D",age:54,eyes:"brown"}]`

#### ANY

Tests whether a predicate holds for at least one element in the collection.

Syntax: `ANY(identifier in collection WHERE predicate)`

Arguments:

- collection: An expression that returns a collection
- identifier: This is the identifier that can be used from the predicate.
- predicate: A predicate that is tested against all items in the collection.

Query.

    START a=node(2)
    WHERE any(x in a.array
    WHERE x = "one")
    RETURN a

All nodes in the returned paths has at least one `one` value set in the array property named `array`.

Result

a
1 row
0 ms
`Node[2]{name:"E",age:41,eyes:"blue",array:["one","two","three"]}`

#### NONE

Returns true if the predicate holds for no element in the collection.

Syntax: `NONE(identifier in collection WHERE predicate)`

Arguments:

- collection: An expression that returns a collection
- identifier: This is the identifier that can be used from the predicate.
- predicate: A predicate that is tested against all items in the collection.

Query.

    START n=node(3)
    MATCH p=n-[*1..3]->b
    WHERE NONE(x in nodes(p)
    WHERE x.age = 25)
    RETURN p

No nodes in the returned paths has a `age` property set to `25`.

Result

p
2 rows
2 ms
`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"}]`
`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[1] {},Node[5]{name:"C",age:53,eyes:"green"},:KNOWS[3] {},Node[1]{name:"D",age:54,eyes:"brown"}]`

#### SINGLE

Returns true if the predicate holds for exactly one of the elements in the collection.

Syntax: `SINGLE(identifier in collection WHERE predicate)`

Arguments:

- collection: An expression that returns a collection
- identifier: This is the identifier that can be used from the predicate.
- predicate: A predicate that is tested against all items in the collection.

Query.

    START n=node(3)
    MATCH p=n-->b
    WHERE SINGLE(var in nodes(p)
    WHERE var.eyes = "blue")
    RETURN p

Exactly one node in every returned path will have the `eyes` property set to `"blue"`.

Result

p
1 row
1 ms
`[Node[3]{name:"A",age:38,eyes:"brown"},:KNOWS[0] {},Node[4]{name:"B",age:25,eyes:"blue"}]`

### 15.23.2. Scalar functions

Scalar functions return a single value.

#### LENGTH

To return or filter on the length of a collection, use the `LENGTH()` function.

Syntax: `LENGTH( collection )`

Arguments:

- collection: An expression that returns a collection

Query.

    START a=node(3)
    MATCH p=a-->b-->c
    RETURN length(p)

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

Result

length(p)
3 rows
1 ms
`2`
`2`
`2`

#### TYPE

Returns a string representation of the relationship type.

Syntax: `TYPE( relationship )`

Arguments:

- relationship: A relationship.

Query.

    START n=node(3)
    MATCH (n)-[r]->()
    RETURN type(r)

The relationship type of `r` is returned by the query.

Result

type(r)
2 rows
0 ms
`"KNOWS"`
`"KNOWS"`

#### ID

Returns the id of the relationship or node.

Syntax: `ID( property-container )`

Arguments:

- property-container: A node or a relationship.

Query.

    START a=node(3, 4, 5)
    RETURN ID(a)

This returns the node id for three nodes.

Result

ID(a)
3 rows
0 ms
`3`
`4`
`5`

#### COALESCE

Returns the first non-`null` value in the list of expressions passed to it.

Syntax: `COALESCE( expression [, expression]* )`

Arguments:

- expression: The expression that might return null.

Query.

    START a=node(3)
    RETURN coalesce(a.hairColour?, a.eyes?)

Result

coalesce(a.hairColour?, a.eyes?)
1 row
0 ms
`"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.

    START a=node(2)
    RETURN a.array, head(a.array)

The first node in the path is returned.

Result

a.array | head(a.array)
--- | ---
1 row
0 ms
`["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.

    START a=node(2)
    RETURN a.array, last(a.array)

The last node in the path is returned.

Result

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

### 15.23.3. Collection functions

Collection functions return collections of things — nodes in a path, and so on.

#### NODES

Returns all nodes in a path.

Syntax: `NODES( path )`

Arguments:

- path: A path.

Query.

    START a=node(3), c=node(2)
    MATCH p=a-->b-->c
    RETURN NODES(p)

All the nodes in the path `p` are returned by the example query.

Result

NODES(p)
1 row
0 ms
`[Node[3]{name:"A",age:38,eyes:"brown"},Node[4]{name:"B",age:25,eyes:"blue"},Node[2]{name:"E",age:41,eyes:"blue",array:["one","two","three"]}]`

#### RELATIONSHIPS

Returns all relationships in a path.

Syntax: `RELATIONSHIPS( path )`

Arguments:

- path: A path.

Query.

    START a=node(3), c=node(2)
    MATCH p=a-->b-->c
    RETURN RELATIONSHIPS(p)

All the relationships in the path `p` are returned.

Result

RELATIONSHIPS(p)
1 row
1 ms
`[:KNOWS[0] {},:MARRIED[4] {}]`

#### EXTRACT

To return a single property, or the value of a function from a collection of nodes or relationships, you can use `EXTRACT`. It will go through a collection, run an expression on every element, and return the results in an collection with these values. It works like the `map` method in functional languages such as Lisp and Scala.

Syntax: `EXTRACT( identifier in collection : expression )`

Arguments:

- collection: An expression that returns a collection
- identifier: The closure will have an identifier introduced in it’s context. Here you decide which identifier to use.
- expression: This expression will run once per value in the collection, and produces the result collection.

Query.

    START a=node(3), b=node(4), c=node(1)
    MATCH p=a-->b-->c
    RETURN extract(n in nodes(p) : n.age)

The age property of all nodes in the path are returned.

Result

extract(n in nodes(p) : n.age)
1 row
1 ms
`[38,25,54]`

#### FILTER

`FILTER` returns all the elements in a collection that comply to a predicate.

Syntax: `FILTER(identifier in collection : predicate)`

Arguments:

- collection: An expression that returns a collection
- identifier: This is the identifier that can be used from the predicate.
- predicate: A predicate that is tested against all items in the collection.

Query.

    START a=node(2)
    RETURN a.array, filter(x in a.array : length(x) = 3)

This returns the property named `array` and a list of values in it, which have the length `3`.

Result

a.array | filter(x in a.array : length(x) = 3)
--- | ---
1 row
0 ms
`["one","two","three"]` | `["one","two"]`

#### TAIL

`TAIL` returns all but the first element in a collection.

Syntax: `TAIL( expression )`

Arguments:

- expression: This expression should return a collection of some kind.

Query.

    START a=node(2)
    RETURN a.array, tail(a.array)

This returns the property named `array` and all elements of that property except the first one.

Result

a.array | tail(a.array)
--- | ---
1 row
0 ms
`["one","two","three"]` | `["two","three"]`

#### RANGE

Returns numerical values in a range with a non-zero step value step. Range is inclusive in both ends.

Syntax: `RANGE( start, end [, step] )`

Arguments:

- start: A numerical expression.
- end: A numerical expression.
- step: A numerical expression.

Query.

    START n=node(1)
    RETURN range(0,10), range(2,18,3)

Two lists of numbers are returned.

Result

range(0,10) | range(2,18,3)
--- | ---
1 row
0 ms
`[0,1,2,3,4,5,6,7,8,9,10]` | `[2,5,8,11,14,17]`

#### REDUCE

To run an expression against individual elements of a collection, and store the result of the expression in an accumulator, you can use `REDUCE`. It will go through a collection, run an expression on every element, storing the partial result in the accumulator. It works like the `fold` or `reduce` method in functional languages such as Lisp and Scala.

Syntax: `REDUCE( accumulator = initial, identifier in collection : expression )`

Arguments:

- accumulator: An identifier that will hold the result and the partial results as the collection is iterated
- initial: An expression that runs once to give a starting value to the accumulator
- collection: An expression that returns a collection
- identifier: The closure will have an identifier introduced in it’s context. Here you decide which identifier to use.
- expression: This expression will run once per value in the collection, and produces the result value.

Query.

    START a=node(3), b=node(4), c=node(1)
    MATCH p=a-->b-->c
    RETURN reduce(totalAge = 0, n in nodes(p) : totalAge + n.age)

The age property of all nodes in the path are summed and returned as a single value.

Result

reduce(totalAge = 0, n in nodes(p) : totalAge + n.age)
1 row
2 ms
`117`

### 15.23.4. Mathematical functions

These functions all operate on numerical expressions only, and will return an error if used on any other values.

#### ABS

`ABS` returns the absolute value of a number.

Syntax: `ABS( expression )`

Arguments:

- expression: A numeric expression.

Query.

    START a=node(3), c=node(2)
    RETURN a.age, c.age, abs(a.age - c.age)

The absolute value of the age difference is returned.

Result

a.age | c.age | abs(a.age - c.age)
--- | --- | ---
1 row
0 ms
`38` | `41` | `3.0`

#### ROUND

`ROUND` returns the numerical expression, rounded to the nearest integer.

Syntax: `ROUND( expression )`

Arguments:

- expression: A numerical expression.

Query.

    START a=node(1)
    RETURN round(3.141592)

Result

round(3.141592)
1 row
0 ms
`3`

#### SQRT

`SQRT` returns the square root of a number.

Syntax: `SQRT( expression )`

Arguments:

- expression: A numerical expression

Query.

    START a=node(1)
    RETURN sqrt(256)

Result

sqrt(256)
1 row
0 ms
`16.0`

#### SIGN

`SIGN` returns the signum of a number — zero if the expression is zero, `-1` for any negative number, and `1` for any positive number.

Syntax: `SIGN( expression )`

Arguments:

- expression: A numerical expression

Query.

    START n=node(1)
    RETURN sign(-17), sign(0.1)

Result

sign(-17) | sign(0.1)
--- | ---
1 row
0 ms
`-1.0` | `1.0`

#### String functions

These functions all operate on string expressions only, and will return an error if used on any other values. Except STR(), which converts to strings.

#### STR

`STR` returns a string representation of the expression.

Syntax: `STR( expression )`

Arguments:

- expression: An expression that returns anything

Query.

    START n=node(1)
    RETURN str(1)

A string.

Result

str(1)
1 row
0 ms
`"1"`

#### REPLACE

`REPLACE` returns a string with the search string replaced by the replace string. It replaces all occurrences.

Syntax: `REPLACE( original, search, replace )`

Arguments:

- original: An expression that returns a string
- search: An expression that returns a string to search for
- replace: An expression that returns the string to replace the search string with

Query.

    START n=node(1)
    RETURN replace("hello", "l", "w")

A string.

Result

replace("hello", "l", "w")
1 row
0 ms
`"hewwo"`

#### SUBSTRING

`SUBSTRING` returns a substring of the original, with a 0-based index start and length. If length is omitted, it returns a substring from start until the end of the string.

Syntax: `SUBSTRING( original, start [, length] )`

Arguments:

- original: An expression that returns a string
- start: An expression that returns a positive number
- length: An expression that returns a positive number

Query.

    START n=node(1)
    RETURN substring("hello", 1, 3), substring("hello", 2)

A string.

Result

substring("hello", 1, 3) | substring("hello", 2)
--- | ---
1 row
0 ms
`"ell"` | `"llo"`

#### LEFT

`LEFT` returns a string containing the left n characters of the original string.

Syntax: `LEFT( original, length )`

Arguments:

- original: An expression that returns a string
- n: An expression that returns a positive number

Query.

    START n=node(1)
    RETURN left("hello", 3)

A String.

Result

left("hello", 3)
1 row
1 ms
`"hel"`

#### RIGHT

`RIGHT` returns a string containing the right n characters of the original string.

Syntax: `RIGHT( original, length )`

Arguments:

- original: An expression that returns a string
- n: An expression that returns a positive number

Query.

    START n=node(1)
    RETURN right("hello", 3)

A string.

Result

right("hello", 3)
1 row
0 ms
`"llo"`

#### LTRIM

`LTRIM` returns the original string with whitespace removed from the left side.

Syntax: `LTRIM( original )`

Arguments:

- original: An expression that returns a string

Query.

    START n=node(1)
    RETURN ltrim("   hello")

A string.

Result

ltrim(" hello")
1 row
0 ms
`"hello"`

#### RTRIM

`RTRIM` returns the original string with whitespace removed from the right side.

Syntax: `RTRIM( original )`

Arguments:

- original: An expression that returns a string

Query.

    START n=node(1)
    RETURN rtrim("hello   ")

A string.

Result

rtrim("hello ")
1 row
0 ms
`"hello"`

#### TRIM

`TRIM` returns the original string with whitespace removed from both sides.

Syntax: `TRIM( original )`

Arguments:

- original: An expression that returns a string

Query.

    START n=node(1)
    RETURN trim("   hello   ")

A string.

Result

trim(" hello ")
1 row
0 ms
`"hello"`

#### LOWER

`LOWER` returns the original string in lowercase.

Syntax: `LOWER( original )`

Arguments:

- original: An expression that returns a string

Query.

    START n=node(1)
    RETURN lower("HELLO")

A string.

Result

lower("HELLO")
1 row
0 ms
`"hello"`

#### UPPER

`UPPER` returns the original string in uppercase.

Syntax: `UPPER( original )`

Arguments:

- original: An expression that returns a string

Query.

    START n=node(1)
    RETURN upper("hello")

A string.

Result

upper("hello")
1 row
0 ms
`"HELLO"`

Copyright © 2013 Neo Technology

Prev | Up | Next
| Home |