Operators
This section contains an overview of operators.
1. Operators at a glance



















2. Aggregation operators
The aggregation operators comprise:

remove duplicates values:
DISTINCT
2.1. Using the DISTINCT
operator
Retrieve the unique eye colors from Person
nodes.
CREATE
(a:Person {name: 'Anne', eyeColor: 'blue'}),
(b:Person {name: 'Bill', eyeColor: 'brown'}),
(c:Person {name: 'Carol', eyeColor: 'blue'})
WITH [a, b, c] AS ps
UNWIND ps AS p
RETURN DISTINCT p.eyeColor
Even though both 'Anne' and 'Carol' have blue eyes, 'blue' is only returned once.
p.eyeColor 



Rows: 2 
DISTINCT
is commonly used in conjunction with aggregating functions.
3. Property operators
The property operators pertain to a node or a relationship, and comprise:

statically access the property of a node or relationship using the dot operator:
.

dynamically access the property of a node or relationship using the subscript operator:
[]

property replacement
=
for replacing all properties of a node or relationship 
property mutation operator
+=
for setting specific properties of a node or relationship
3.1. Statically accessing a property of a node or relationship using the .
operator
CREATE
(a:Person {name: 'Jane', livesIn: 'London'}),
(b:Person {name: 'Tom', livesIn: 'Copenhagen'})
WITH a, b
MATCH (p:Person)
RETURN p.name
p.name 



Rows: 2 
3.2. Filtering on a dynamicallycomputed property key using the []
operator
CREATE
(a:Restaurant {name: 'Hungry Jo', rating_hygiene: 10, rating_food: 7}),
(b:Restaurant {name: 'Buttercup Tea Rooms', rating_hygiene: 5, rating_food: 6}),
(c1:Category {name: 'hygiene'}),
(c2:Category {name: 'food'})
WITH a, b, c1, c2
MATCH (restaurant:Restaurant), (category:Category)
WHERE restaurant["rating_" + category.name] > 6
RETURN DISTINCT restaurant.name
restaurant.name 


Rows: 1 
See Basic usage for more details on dynamic property access.
The behavior of the 
3.3. Replacing all properties of a node or relationship using the =
operator
CREATE (a:Person {name: 'Jane', age: 20})
WITH a
MATCH (p:Person {name: 'Jane'})
SET p = {name: 'Ellen', livesIn: 'London'}
RETURN p.name, p.age, p.livesIn
All the existing properties on the node are replaced by those provided in the map; i.e. the name
property is updated from Jane
to Ellen
, the age
property is deleted, and the livesIn
property is added.
p.name  p.age  p.livesIn 




Rows: 1 
See Replace all properties using a map and =
for more details on using the property replacement operator =
.
3.4. Mutating specific properties of a node or relationship using the +=
operator
CREATE (a:Person {name: 'Jane', age: 20})
WITH a
MATCH (p:Person {name: 'Jane'})
SET p += {name: 'Ellen', livesIn: 'London'}
RETURN p.name, p.age, p.livesIn
The properties on the node are updated as follows by those provided in the map: the name
property is updated from Jane
to Ellen
, the age
property is left untouched, and the livesIn
property is added.
p.name  p.age  p.livesIn 




Rows: 1 
See Mutate specific properties using a map and +=
for more details on using the property mutation operator +=
.
4. Mathematical operators
5. Comparison operators
The comparison operators comprise:

equality:
=

inequality:
<>

less than:
<

greater than:
>

less than or equal to:
<=

greater than or equal to:
>=

IS NULL

IS NOT NULL
5.1. Stringspecific comparison operators comprise:

STARTS WITH
: perform casesensitive prefix searching on strings 
ENDS WITH
: perform casesensitive suffix searching on strings 
CONTAINS
: perform casesensitive inclusion searching in strings
5.2. Comparing two numbers
WITH 4 AS one, 3 AS two
RETURN one > two AS result
result 


Rows: 1 
See Equality and comparison of values for more details on the behavior of comparison operators, and Using ranges for more examples showing how these may be used.
5.3. Using STARTS WITH
to filter names
WITH ['John', 'Mark', 'Jonathan', 'Bill'] AS somenames
UNWIND somenames AS names
WITH names AS candidate
WHERE candidate STARTS WITH 'Jo'
RETURN candidate
candidate 



Rows: 2 
String matching contains more information regarding the stringspecific comparison operators as well as additional examples illustrating the usage thereof.
5.4. Equality and comparison of values
5.4.1. Equality
Cypher supports comparing values (see Values and types) by equality using the =
and <>
operators.
Values of the same type are only equal if they are the same identical value (e.g. 3 = 3
and "x" <> "xy"
).
Maps are only equal if they map exactly the same keys to equal values and lists are only equal if they contain the same sequence of equal values (e.g. [3, 4] = [1+2, 8/2]
).
Values of different types are considered as equal according to the following rules:

Paths are treated as lists of alternating nodes and relationships and are equal to all lists that contain that very same sequence of nodes and relationships.

Testing any value against
null
with both the=
and the<>
operators always isnull
. This includesnull = null
andnull <> null
. The only way to reliably test if a valuev
isnull
is by using the specialv IS NULL
, orv IS NOT NULL
equality operators.
All other combinations of types of values cannot be compared with each other. Especially, nodes, relationships, and literal maps are incomparable with each other.
It is an error to compare values that cannot be compared.
5.5. Ordering and comparison of values
The comparison operators <=
, <
(for ascending) and >=
, >
(for descending) are used to compare values for ordering.
The following points give some details on how the comparison is performed.

Numerical values are compared for ordering using numerical order (e.g.
3 < 4
is true). 
The special value
java.lang.Double.NaN
is regarded as being larger than all other numbers. 
String values are compared for ordering using lexicographic order (e.g.
"x" < "xy"
). 
Boolean values are compared for ordering such that
false < true
. 
Comparison of spatial values:

Point values can only be compared within the same Coordinate Reference System (CRS) — otherwise, the result will be
null
. 
For two points
a
andb
within the same CRS,a
is considered to be greater thanb
ifa.x > b.x
anda.y > b.y
(anda.z > b.z
for 3D points). 
a
is considered less thanb
ifa.x < b.x
anda.y < b.y
(anda.z < b.z
for 3D points). 
If none if the above is true, the points are considered incomparable and any comparison operator between them will return
null
.


Ordering of spatial values:

ORDER BY
requires all values to be orderable. 
Points are ordered after arrays and before temporal types.

Points of different CRS are ordered by the CRS code (the value of SRID field). For the currently supported set of Coordinate Reference Systems this means the order: 4326, 4979, 7302, 9157

Points of the same CRS are ordered by each coordinate value in turn,
x
first, theny
and finallyz
. 
Note that this order is different to the order returned by the spatial index, which will be the order of the space filling curve.


Comparison of temporal values:

Temporal instant values are comparable within the same type. An instant is considered less than another instant if it occurs before that instant in time, and it is considered greater than if it occurs after.

Instant values that occur at the same point in time — but that have a different time zone — are not considered equal, and must therefore be ordered in some predictable way. Cypher prescribes that, after the primary order of point in time, instant values be ordered by effective time zone offset, from west (negative offset from UTC) to east (positive offset from UTC). This has the effect that times that represent the same point in time will be ordered with the time with the earliest local time first. If two instant values represent the same point in time, and have the same time zone offset, but a different named time zone (this is possible for DateTime only, since Time only has an offset), these values are not considered equal, and ordered by the time zone identifier, alphabetically, as its third ordering component. If the type, point in time, offset, and time zone name are all equal, then the values are equal, and any difference in order is impossible to observe.

Duration values cannot be compared, since the length of a day, month or year is not known without knowing which day, month or year it is. Since Duration values are not comparable, the result of applying a comparison operator between two Duration values is
null
.


Ordering of temporal values:

ORDER BY
requires all values to be orderable. 
Temporal instances are ordered after spatial instances and before strings.

Comparable values should be ordered in the same order as implied by their comparison order.

Temporal instant values are first ordered by type, and then by comparison order within the type.

Since no complete comparison order can be defined for Duration values, we define an order for
ORDER BY
specifically for Duration:
Duration values are ordered by normalising all components as if all years were
365.2425
days long (PT8765H49M12S
), all months were30.436875
(1/12
year) days long (PT730H29M06S
), and all days were24
hours long ^{[1]}.



Comparing for ordering when one argument is
null
(e.g.null < 3
isnull
). 
Ordering of values with different types:

Ordering of composite type values:

For the composite types (e.g. maps and lists), elements of the containers are compared pairwise for ordering and thus determine the ordering of two container types. For example,
[1, 'foo', 3]
is ordered before[1, 2, 'bar']
since'foo'
is ordered before2
.

5.6. Chaining comparison operations
Comparisons can be chained arbitrarily, e.g., x < y <= z
is equivalent to x < y AND y <= z
.
Formally, if a, b, c, ..., y, z
are expressions and op1, op2, ..., opN
are comparison operators, then a op1 b op2 c ... y opN z
is equivalent to a op1 b and b op2 c and ... y opN z
.
Note that a op1 b op2 c
does not imply any kind of comparison between a
and c
, so that, e.g., x < y > z
is perfectly legal (although perhaps not elegant).
The example:
MATCH (n) WHERE 21 < n.age <= 30 RETURN n
is equivalent to
MATCH (n) WHERE 21 < n.age AND n.age <= 30 RETURN n
Thus it will match all nodes where the age is between 21 and 30.
This syntax extends to all equality and inequality comparisons, as well as extending to chains longer than three.
For example:
a < b = c <= d <> e
Is equivalent to:
a < b AND b = c AND c <= d AND d <> e
6. Boolean operators
The boolean operators — also known as logical operators — comprise:

conjunction:
AND

disjunction:
OR
, 
exclusive disjunction:
XOR

negation:
NOT
Here is the truth table for AND
, OR
, XOR
and NOT
.
a  b  a AND b 
a OR b 
a XOR b 
NOT a 























































7. String operators
The string operators comprise:

concatenating strings:
+

matching a regular expression:
=~
7.1. Using a regular expression with =~
to filter words
WITH ['mouse', 'chair', 'door', 'house'] AS wordlist
UNWIND wordlist AS word
WITH word
WHERE word =~ '.*ous.*'
RETURN word
word 



Rows: 2 
Further information and examples regarding the use of regular expressions in filtering can be found in Regular expressions. In addition, refer to Stringspecific comparison operators comprise: for details on stringspecific comparison operators.
8. Temporal operators
Temporal operators comprise:

adding a Duration to either a temporal instant or another Duration:
+

subtracting a Duration from either a temporal instant or another Duration:


multiplying a Duration with a number:
*

dividing a Duration by a number:
/
The following table shows — for each combination of operation and operand type — the type of the value returned from the application of each temporal operator:
Operator  Lefthand operand  Righthand operand  Type of result 

Temporal instant 
Duration 
The type of the temporal instant 

Duration 
Temporal instant 
The type of the temporal instant 

Temporal instant 
Duration 
The type of the temporal instant 

Duration 
Duration 
Duration 

Duration 
Duration 
Duration 

Duration 
Duration 

Duration 
Duration 

Duration 
Duration 
8.1. Adding and subtracting a Duration to or from a temporal instant
WITH
localdatetime({year:1984, month:10, day:11, hour:12, minute:31, second:14}) AS aDateTime,
duration({years: 12, nanoseconds: 2}) AS aDuration
RETURN aDateTime + aDuration, aDateTime  aDuration
aDateTime + aDuration  aDateTime  aDuration 



Rows: 1 
Components of a Duration that do not apply to the temporal instant are ignored. For example, when adding a Duration to a Date, the hours, minutes, seconds and nanoseconds of the Duration are ignored (Time behaves in an analogous manner):
WITH
date({year:1984, month:10, day:11}) AS aDate,
duration({years: 12, nanoseconds: 2}) AS aDuration
RETURN aDate + aDuration, aDate  aDuration
aDate + aDuration  aDate  aDuration 



Rows: 1 
Adding two durations to a temporal instant is not an associative operation. This is because nonexisting dates are truncated to the nearest existing date:
RETURN
(date("20110131") + duration("P1M")) + duration("P12M") AS date1,
date("20110131") + (duration("P1M") + duration("P12M")) AS date2
date1  date2 



Rows: 1 
8.2. Adding and subtracting a Duration to or from another Duration
WITH
duration({years: 12, months: 5, days: 14, hours: 16, minutes: 12, seconds: 70, nanoseconds: 1}) as duration1,
duration({months:1, days: 14, hours: 16, minutes: 12, seconds: 70}) AS duration2
RETURN duration1, duration2, duration1 + duration2, duration1  duration2
duration1  duration2  duration1 + duration2  duration1  duration2 





Rows: 1 
8.3. Multiplying and dividing a Duration with or by a number
These operations are interpreted simply as componentwise operations with overflow to smaller units based on an average length of units in the case of division (and multiplication with fractions).
WITH duration({days: 14, minutes: 12, seconds: 70, nanoseconds: 1}) AS aDuration
RETURN aDuration, aDuration * 2, aDuration / 3
aDuration  aDuration * 2  aDuration / 3 




Rows: 1 
9. Map operators
The map operators comprise:

statically access the value of a map by key using the dot operator:
.

dynamically access the value of a map by key using the subscript operator:
[]
The behavior of the 
9.1. Statically accessing the value of a nested map by key using the .
operator
WITH {person: {name: 'Anne', age: 25}} AS p
RETURN p.person.name
p.person.name 


Rows: 1 
9.2. Dynamically accessing the value of a map by key using the []
operator and a parameter
A parameter may be used to specify the key of the value to access:
{
"myKey" : "name"
}
WITH {name: 'Anne', age: 25} AS a
RETURN a[$myKey] AS result
result 


Rows: 1 
More details on maps can be found in Maps.
10. List operators
The list operators comprise:

concatenating lists
l_{1}
andl_{2}
:[l_{1}] + [l_{2}]

checking if an element
e
exists in a listl
:e IN [l]

dynamically accessing an element(s) in a list using the subscript operator:
[]
The behavior of the 
10.1. Concatenating two lists using +
RETURN [1,2,3,4,5] + [6,7] AS myList
myList 


Rows: 1 
10.2. Using IN
to check if a number is in a list
WITH [2, 3, 4, 5] AS numberlist
UNWIND numberlist AS number
WITH number
WHERE number IN [2, 3, 8]
RETURN number
number 



Rows: 2 
10.3. Using IN
for more complex list membership operations
The general rule is that the IN
operator will evaluate to true
if the list given as the righthand operand contains an element which has the same type and contents (or value) as the lefthand operand.
Lists are only comparable to other lists, and elements of a list innerList
are compared pairwise in ascending order from the first element in innerList
to the last element in innerList
.
The following query checks whether or not the list [2, 1]
is an element of the list [1, [2, 1], 3]
:
RETURN [2, 1] IN [1, [2, 1], 3] AS inList
The query evaluates to true
as the righthand list contains, as an element, the list [1, 2]
which is of the same type (a list) and contains the same contents (the numbers 2
and 1
in the given order) as the lefthand operand.
If the lefthand operator had been [1, 2]
instead of [2, 1]
, the query would have returned false
.
inList 


Rows: 1 
At first glance, the contents of the lefthand operand and the righthand operand appear to be the same in the following query:
RETURN [1, 2] IN [1, 2] AS inList
However, IN
evaluates to false
as the righthand operand does not contain an element that is of the same type — i.e. a list — as the lefthandoperand.
inList 


Rows: 1 
The following query can be used to ascertain whether or not a list — obtained from, say, the labels() function — contains at least one element that is also present in another list:
MATCH (n)
WHERE size([label IN labels(n) WHERE label IN ['Person', 'Employee']  1]) > 0
RETURN count(n)
As long as labels(n)
returns either Person
or Employee
(or both), the query will return a value greater than zero.
10.4. Accessing elements in a list using the []
operator
WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names
RETURN names[1..3] AS result
The square brackets will extract the elements from the start index 1
, and up to (but excluding) the end index 3
.
result 


Rows: 1 
10.5. Dynamically accessing an element in a list using the []
operator and a parameter
A parameter may be used to specify the index of the element to access:
{
"myIndex" : 1
}
WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names
RETURN names[$myIndex] AS result
result 


Rows: 1 
10.6. Using IN
with []
on a nested list
IN
can be used in conjunction with []
to test whether an element exists in a nested list:
{
"myIndex" : 1
}
WITH [[1, 2, 3]] AS l
RETURN 3 IN l[0] AS result
result 


Rows: 1 
More details on lists can be found in Lists in general.
365.2425
days per year comes from the frequency of leap years. A leap year occurs on a year with an ordinal number divisible by 4
, that is not divisible by 100
, unless it divisible by 400
. This means that over 400
years there are ((365 * 4 + 1) * 25  1) * 4 + 1 = 146097
days, which means an average of 365.2425
days per year.
Was this page helpful?