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
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.
See also Section 14.1.2, “Comparison operators”.
Tests whether a predicate holds for all element of this collection collection.
Syntax: ALL(identifier in collection WHERE predicate)
Arguments:
Query.
MATCH p=a-[*1..3]->b WHERE a.name='Alice' and b.name='Daniel' and 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 |
2 ms |
|
Tests whether a predicate holds for at least one element in the collection.
Syntax: ANY(identifier in collection WHERE predicate)
Arguments:
Query.
MATCH a WHERE a.name='Eskil' and 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
.
Returns true if the predicate holds for no element in the collection.
Syntax: NONE(identifier in collection WHERE predicate)
Arguments:
Query.
MATCH p=n-[*1..3]->b WHERE n.name='Alice' and 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 |
|
|
Returns true if the predicate holds for exactly one of the elements in the collection.
Syntax: SINGLE(identifier in collection WHERE predicate)
Arguments:
Query.
MATCH p=n-->b WHERE n.name='Alice' and 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 |
0 ms |
|
Scalar functions return a single value.
To return or filter on the length of a collection, use the LENGTH()
function.
Syntax: LENGTH( collection )
Arguments:
Query.
MATCH p=a-->b-->c WHERE a.name='Alice' RETURN length(p)
The length of the path p
is returned by the query.
Returns a string representation of the relationship type.
Syntax: TYPE( relationship )
Arguments:
Query.
MATCH (n)-[r]->() WHERE n.name='Alice' RETURN type(r)
The relationship type of r
is returned by the query.
Returns the id of the relationship or node.
Syntax: ID( property-container )
Arguments:
Query.
MATCH a RETURN ID(a)
This returns the node id for three nodes.
Returns the first non-null
value in the list of expressions passed to it.
Syntax: COALESCE( expression [, expression]* )
Arguments:
Query.
MATCH a WHERE a.name='Alice' RETURN coalesce(a.hairColour?, a.eyes?)
HEAD
returns the first element in a collection.
Syntax: HEAD( expression )
Arguments:
Query.
MATCH a WHERE a.name='Eskil' RETURN a.array, head(a.array)
The first node in the path is returned.
LAST
returns the last element in a collection.
Syntax: LAST( expression )
Arguments:
Query.
MATCH a WHERE a.name='Eskil' RETURN a.array, last(a.array)
The last node in the path is returned.
Collection functions return collections of things — nodes in a path, and so on.
See also Section 14.1.4, “Collection operators”.
Returns all nodes in a path.
Syntax: NODES( path )
Arguments:
Query.
MATCH p=a-->b-->c WHERE a.name='Alice' and c.name='Eskil' RETURN NODES(p)
All the nodes in the path p
are returned by the example query.
Result
NODES(p) |
---|
1 row |
1 ms |
|
Returns all relationships in a path.
Syntax: RELATIONSHIPS( path )
Arguments:
Query.
MATCH p=a-->b-->c WHERE a.name='Alice' and c.name='Eskil' RETURN RELATIONSHIPS(p)
All the relationships in the path p
are returned.
Returns a collection of string representations for the labels attached to a node.
Syntax: LABELS( node )
Arguments:
Query.
MATCH a WHERE a.name='Alice' RETURN labels(a)
The labels of n
is returned by the query.
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:
Query.
MATCH p=a-->b-->c WHERE a.name='Alice' and b.name='Bob' and c.name='Daniel' RETURN extract(n in nodes(p) : n.age)
The age property of all nodes in the path are returned.
FILTER
returns all the elements in a collection that comply to a predicate.
Syntax: FILTER(identifier in collection : predicate)
Arguments:
Query.
MATCH a WHERE a.name='Eskil' 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
.
TAIL
returns all but the first element in a collection.
Syntax: TAIL( expression )
Arguments:
Query.
MATCH a WHERE a.name='Eskil' RETURN a.array, tail(a.array)
This returns the property named array
and all elements of that property except the first one.
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:
Query.
MATCH n RETURN range(0,10), range(2,18,3) LIMIT 1
Two lists of numbers are returned.
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:
Query.
MATCH p=a-->b-->c WHERE a.name='Alice' and b.name='Bob' and c.name='Daniel' 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.
These functions all operate on numerical expressions only, and will return an error if used on any other values.
See also Section 14.1.1, “Mathematical operators”.
ABS
returns the absolute value of a number.
Syntax: ABS( expression )
Arguments:
Query.
MATCH a, e WHERE a.name = 'Alice' and e.name = 'Eskil' RETURN a.age, e.age, abs(a.age - e.age)
The absolute value of the age difference is returned.
ROUND
returns the numerical expression, rounded to the nearest integer.
Syntax: ROUND( expression )
Arguments:
Query.
MATCH a RETURN round(3.141592) LIMIT 1
SQRT
returns the square root of a number.
Syntax: SQRT( expression )
Arguments:
Query.
MATCH n RETURN sqrt(256) LIMIT 1
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.
See also Section 14.1.3, “String operators”.
STR
returns a string representation of the expression.
Syntax: STR( expression )
Arguments:
Query.
MATCH a RETURN str(1) LIMIT 1
A string.
REPLACE
returns a string with the search string replaced by the replace string. It replaces all occurrences.
Syntax: REPLACE( original, search, replace )
Arguments:
Query.
MATCH a RETURN replace("hello", "l", "w") LIMIT 1
A string.
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:
Query.
MATCH n RETURN substring("hello", 1, 3), substring("hello", 2) LIMIT 1
A string.
LEFT
returns a string containing the left n characters of the original string.
Syntax: LEFT( original, length )
Arguments:
Query.
MATCH n RETURN left("hello", 3) LIMIT 1
A String.
RIGHT
returns a string containing the right n characters of the original string.
Syntax: RIGHT( original, length )
Arguments:
Query.
MATCH n RETURN right("hello", 3) LIMIT 1
A string.
LTRIM
returns the original string with whitespace removed from the left side.
Syntax: LTRIM( original )
Arguments:
Query.
MATCH n RETURN ltrim(" hello") LIMIT 1
A string.
RTRIM
returns the original string with whitespace removed from the right side.
Syntax: RTRIM( original )
Arguments:
Query.
MATCH n RETURN rtrim("hello ") LIMIT 1
A string.
TRIM
returns the original string with whitespace removed from both sides.
Syntax: TRIM( original )
Arguments:
Query.
MATCH n RETURN trim(" hello ") LIMIT 1
A string.
LOWER
returns the original string in lowercase.
Syntax: LOWER( original )
Arguments:
Query.
MATCH n RETURN lower("HELLO") LIMIT 1
A string.
UPPER
returns the original string in uppercase.
Syntax: UPPER( original )
Arguments:
Query.
MATCH a RETURN upper("hello") LIMIT 1
A string.
Cypher supports CASE expressions, which is a generic conditional expression, similar to if/else statements in other
languages. Two variants of CASE
exist - the simple form and the generic form.
The expression is calculated, and compared in order with the WHEN
clauses until a match is found. If no match is found
the expression in the ELSE
clause is used, or null, if no ELSE
case exists.
Syntax: +CASE+ in
+WHEN+ value +THEN+ result
[+WHEN+ ...]
[+ELSE+ default]
+END+
Arguments:
Query.
MATCH n RETURN CASE n.eyes WHEN 'blue' THEN 1 WHEN 'brown' THEN 2 ELSE 3 END as result
A string.
The predicates are evaluated in order until a true value is found, and the result value is used.If no match is found the expression in the +ELSE + clause is used, or null, if no + ELSE + case exists.
Syntax: +CASE+
+WHEN+ predicate +THEN+ result
[+WHEN+ ...]
[+ELSE+ result]
+END+
Arguments:
Query.
MATCH n RETURN CASE WHEN n.eyes = 'blue' THEN 1 WHEN n.age < 40 THEN 2 ELSE 3 END as result
A string.
Copyright © 2013 Neo Technology