Operators

This page contains an overview of the available Cypher® operators.

Operators at a glance

Aggregation operators

DISTINCT

Property operators

. for static property access, [] for dynamic property access, = for replacing all properties, += for mutating specific properties

Mathematical operators

+, -, *, /, %, ^

String operators

+ and || (string concatenation), IS NORMALIZED

Temporal operators

+ and - for operations between durations and temporal instants/durations, * and / for operations between durations and numbers

Map operators

. for static value access by key, [] for dynamic value access by key

List operators

+ and || (list concatenation), IN to check existence of an element in a list, [] for accessing element(s) dynamically

Aggregation operators

The aggregation operators comprise:

  • remove duplicates values: DISTINCT

Using the DISTINCT operator

Retrieve the unique eye colors from Person nodes.

Query
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.

Table 1. Result
p.eyeColor

"blue"

"brown"

Rows: 2

DISTINCT is commonly used in conjunction with aggregating functions.

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

Statically accessing a property of a node or relationship using the . operator

Query
CREATE
  (a:Person {name: 'Jane', livesIn: 'London'}),
  (b:Person {name: 'Tom', livesIn: 'Copenhagen'})
WITH a, b
MATCH (p:Person)
RETURN  p.name
Table 2. Result
p.name

"Jane"

"Tom"

Rows: 2

Filtering on a dynamically-computed property key using the [] operator

Query
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
Table 3. Result
restaurant.name

"Hungry Jo"

Rows: 1

See also WHERE → Filter on dynamic properties.

The behavior of the [] operator with respect to null is detailed here.

Replacing all properties of a node or relationship using the = operator

Query
CREATE (a:Person {name: 'Sofia', age: 20})
WITH a
MATCH (p:Person {name: 'Sofia'})
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 Sofia to Ellen, the age property is deleted, and the livesIn property is added.

Table 4. Result
p.name p.age p.livesIn

"Ellen"

<null>

"London"

Rows: 1

See Replace all properties using a map and = for more details on using the property replacement operator =.

Mutating specific properties of a node or relationship using the += operator

Query
CREATE (a:Person {name: 'Sofia', age: 20})
WITH a
MATCH (p:Person {name: 'Sofia'})
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 Sofia to Ellen, the age property is left untouched, and the livesIn property is added.

Table 5. Result
p.name p.age p.livesIn

"Ellen"

20

"London"

Rows: 1

See xref::clauses/set.adoc#set-setting-properties-using-map[Mutate specific properties using a map and =`] for more details on using the property mutation operator `=.

Mathematical operators

The mathematical operators comprise:

  • addition: +

  • subtraction or unary minus: -

  • multiplication: *

  • division: /

  • modulo division: %

  • exponentiation: ^

Using the exponentiation operator ^

Query
WITH 2 AS number, 3 AS exponent
RETURN number ^ exponent AS result
Table 6. Result
result

8.0

Rows: 1

Using the unary minus operator -

Query
WITH -3 AS a, 4 AS b
RETURN b - a AS result
Table 7. Result
result

7

Rows: 1

String operators

The string operators comprise:

  • concatenating STRING values: + and ||

  • checking if a STRING is normalized: IS NORMALIZED

Concatenating two STRING values with +

Using ` to concatenate strings is functionally equivalent to using `||`. However, the ` string concatenation operator is not GQL conformant.

Query
RETURN 'neo' + '4j' AS result
Table 8. Result
result

"neo4j"

Rows: 1

Concatenating two STRING values with ||

Query
RETURN 'neo' || '4j' AS result
Table 9. Result
result

"neo4j"

Rows: 1

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 Left-hand operand Right-hand 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

Number

DURATION

*

Number

DURATION

DURATION

/

DURATION

Number

DURATION

Adding and subtracting a DURATION to or from a temporal instant

Query
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
Table 10. Result
aDateTime + aDuration aDateTime - aDuration

1996-10-11T12:31:14.000000002

1972-10-11T12:31:13.999999998

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 (ZONED TIME and LOCAL TIME behaves in an analogous manner):

Query
WITH
  date({year:1984, month:10, day:11}) AS aDate,
  duration({years: 12, nanoseconds: 2}) AS aDuration
RETURN aDate + aDuration, aDate - aDuration
Table 11. Result
aDate + aDuration aDate - aDuration

1996-10-11

1972-10-11

Rows: 1

Adding two durations to a temporal instant is not an associative operation. This is because non-existing dates are truncated to the nearest existing date:

Query
RETURN
  (date("2011-01-31") + duration("P1M")) + duration("P12M") AS date1,
  date("2011-01-31") + (duration("P1M") + duration("P12M")) AS date2
Table 12. Result
date1 date2

2012-02-28

2012-02-29

Rows: 1

Adding and subtracting a DURATION to or from another DURATION

Query
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
Table 13. Result
duration1 duration2 duration1 + duration2 duration1 - duration2

P12Y5M14DT16H13M10.000000001S

P1M-14DT15H49M10S

P12Y6MT32H2M20.000000001S

P12Y4M28DT24M0.000000001S

Rows: 1

Multiplying and dividing a DURATION with or by a number

These operations are interpreted simply as component-wise operations with overflow to smaller units based on an average length of units in the case of division (and multiplication with fractions).

Query
WITH duration({days: 14, minutes: 12, seconds: 70, nanoseconds: 1}) AS aDuration
RETURN aDuration, aDuration * 2, aDuration / 3
Table 14. Result
aDuration aDuration * 2 aDuration / 3

P14DT13M10.000000001S

P28DT26M20.000000002S

P4DT16H4M23.333333333S

Rows: 1

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 [] operator with respect to null is detailed in the working with null page.

Statically accessing the value of a nested map by key using the . operator

Query
WITH {person: {name: 'Anne', age: 25}} AS p
RETURN  p.person.name
Table 15. Result
p.person.name

"Anne"

Rows: 1

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:

Parameters
{
  "myKey" : "name"
}
Query
WITH {name: 'Anne', age: 25} AS a
RETURN a[$myKey] AS result
Table 16. Result
result

"Anne"

Rows: 1

More information can be found in the Maps chapter.

List operators

The list operators comprise:

  • concatenating lists l1 and l2: [l1] + [l2] and [l1] || [l2]

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

  • dynamically accessing an element(s) in a list using the subscript operator: []

The behavior of the IN and [] operators with respect to null is detailed here.

Concatenating two lists using +

Query
RETURN [1,2,3,4,5] + [6,7] AS myList
Table 17. Result
myList

[1,2,3,4,5,6,7]

Rows: 1

Concatenating two lists using ||

Query
RETURN [1,2,3,4,5] || [6,7] AS myList
Table 18. Result
myList

[1,2,3,4,5,6,7]

Rows: 1

Using IN to check if a number is in a list

Query
WITH [2, 3, 4, 5] AS numberlist
UNWIND numberlist AS number
WITH number
WHERE number IN [2, 3, 8]
RETURN number
Table 19. Result
number

2

3

Rows: 2

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 right-hand operand contains an element which has the same type and contents (or value) as the left-hand 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]:

Query
RETURN [2, 1] IN [1, [2, 1], 3] AS inList

The query evaluates to true as the right-hand 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 left-hand operand. If the left-hand operator had been [1, 2] instead of [2, 1], the query would have returned false.

Table 20. Result
inList

true

Rows: 1

At first glance, the contents of the left-hand operand and the right-hand operand appear to be the same in the following query:

Query
RETURN [1, 2] IN [1, 2] AS inList

However, IN evaluates to false as the right-hand operand does not contain an element that is of the same type — i.e. a list — as the left-hand-operand.

Table 21. Result
inList

false

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.

Accessing elements in a list using the [] operator

Query
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.

Table 22. Result
result

["John","Bill"]

Rows: 1

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:

Parameters
{
  "myIndex" : 1
}
Query
WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names
RETURN names[$myIndex] AS result
Table 23. Result
result

"John"

Rows: 1

Using IN with [] on a nested list

IN can be used in conjunction with [] to test whether an element exists in a nested list:

Query
WITH [[1, 2, 3]] AS l
RETURN 3 IN l[0] AS result
Table 24. Result
result

true

Rows: 1

More details on lists can be found in Lists in general.