### 3.2.5. Operators

#### 3.2.5.1. Operators at a glance

 General operators `DISTINCT`, `.` for property access, `[]` for dynamic property access Mathematical operators `+`, `-`, `*`, `/`, `%`, `^` Comparison operators `=`, `<>`, `<`, `>`, `<=`, `>=`, `IS NULL`, `IS NOT NULL` String-specific comparison operators `STARTS WITH`, `ENDS WITH`, `CONTAINS` Boolean operators `AND`, `OR`, `XOR`, `NOT` String operators `+` for concatenation, `=~` for regex matching List operators `+` for concatenation, `IN` to check existence of an element in a list, `[]` for accessing element(s)

#### 3.2.5.2. General operators

The general operators comprise:

• remove duplicates values: `DISTINCT`
• access the property of a node, relationship or literal map using the dot operator: `.`
• dynamic property access using the subscript operator: `[]`
##### 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 3.5. Result
p.eyeColor

2 rows Nodes created: 3 Properties set: 6 Labels added: 3

`"blue"`

`"brown"`

Try this query live.  none 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

`DISTINCT` is commonly used in conjunction with aggregating functions.

##### Accessing properties of a nested literal map using the `.` operator

Query.

``````WITH { person: { name: 'Anne', age: 25 }} AS p
RETURN p.person.name``````

Table 3.6. Result
p.person.name

1 row

`"Anne"`

Try this query live.  none WITH {person: {name: 'Anne', age: 25}} AS p RETURN p.person.name

##### 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.7. Result
restaurant.name

1 row Nodes created: 4 Properties set: 8 Labels added: 4

`"Hungry Jo"`

Try this query live.  none 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

See Section 3.3.7.2, “Basic usage” for more details on dynamic property access.

#### 3.2.5.3. 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 3.8. Result
result

1 row

`8.0`

Try this query live.  none WITH 2 AS number, 3 AS exponent RETURN number ^ exponent AS result

##### Using the unary minus operator `-`

Query.

``````WITH -3 AS a, 4 AS b
RETURN b - a AS result``````

Table 3.9. Result
result

1 row

`7`

Try this query live.  none WITH -3 AS a, 4 AS b RETURN b - a AS result

#### 3.2.5.4. 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`
##### String-specific comparison operators comprise:
• `STARTS WITH`: perform case-sensitive prefix searching on strings
• `ENDS WITH`: perform case-sensitive suffix searching on strings
• `CONTAINS`: perform case-sensitive inclusion searching in strings
##### Comparing two numbers

Query.

``````WITH 4 AS one, 3 AS two
RETURN one > two AS result``````

Table 3.10. Result
result

1 row

`true`

Try this query live.  none WITH 4 AS one, 3 AS two RETURN one > two AS result

See Section 3.2.5.9, “Equality and comparison of values” for more details on the behavior of comparison operators, and Section 3.3.7.8, “Using ranges” for more examples showing how these may be used.

##### Using `STARTS WITH` to filter names

Query.

``````WITH ['John', 'Mark', 'Jonathan', 'Bill'] AS somenames
UNWIND somenames AS names
WITH names AS candidate
WHERE candidate STARTS WITH 'Jo'
RETURN candidate``````

Table 3.11. Result
candidate

2 rows

`"John"`

`"Jonathan"`

Try this query live.  none WITH ['John', 'Mark', 'Jonathan', 'Bill'] AS somenames UNWIND somenames AS names WITH names AS candidate WHERE candidate STARTS WITH 'Jo' RETURN candidate

Section 3.3.7.3, “String matching” contains more information regarding the string-specific comparison operators as well as additional examples illustrating the usage thereof.

#### 3.2.5.5. 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

`false`

`false`

`false`

`false`

`false`

`true`

`false`

`null`

`false`

`null`

`null`

`true`

`false`

`true`

`false`

`true`

`true`

`true`

`true`

`false`

`false`

`true`

`true`

`false`

`true`

`null`

`null`

`true`

`null`

`false`

`true`

`true`

`true`

`true`

`false`

`false`

`null`

`false`

`false`

`null`

`null`

`null`

`null`

`null`

`null`

`null`

`null`

`null`

`null`

`true`

`null`

`true`

`null`

`null`

##### Using boolean operators to filter numbers

Query.

``````WITH [2, 4, 7, 9, 12] AS numberlist
UNWIND numberlist AS number
WITH number
WHERE number = 4 OR (number > 6 AND number < 10)
RETURN number``````

Table 3.12. Result
number

3 rows

`4`

`7`

`9`

Try this query live.  none WITH [2, 4, 7, 9, 12] AS numberlist UNWIND numberlist AS number WITH number WHERE number = 4 OR (number > 6 AND number < 10) RETURN number

#### 3.2.5.6. String operators

String operators comprise:

• concatenating strings: `+`
• matching a regular expression: `=~`
##### Using a regular expression with `=~` to filter words

Query.

``````WITH ['mouse', 'chair', 'door', 'house'] AS wordlist
UNWIND wordlist AS word
WITH word
WHERE word =~ '.*ous.*'
RETURN word``````

Table 3.13. Result
word

2 rows

`"mouse"`

`"house"`

Try this query live.  none WITH ['mouse', 'chair', 'door', 'house'] AS wordlist UNWIND wordlist AS word WITH word WHERE word =~ '.*ous.*' RETURN word

Further information and examples regarding the use of regular expressions in filtering can be found in Section 3.3.7.4, “Regular expressions”. In addition, refer to the section called “String-specific comparison operators comprise:” for details on string-specific comparison operators.

#### 3.2.5.7. List operators

List operators comprise:

• concatenating lists: `+`
• checking if an element exists in a list: `IN`
• accessing an element(s) in a list using the subscript operator: `[]`
##### Concatenating two lists using `+`

Query.

``RETURN [1,2,3,4,5]+[6,7] AS myList``

Table 3.14. Result
myList

1 row

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

Try this query live.  none RETURN [1,2,3,4,5] + [6,7] AS myList

##### 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 3.15. Result
number

2 rows

`2`

`3`

Try this query live.  none WITH [2, 3, 4, 5] AS numberlist UNWIND numberlist AS number WITH number WHERE number IN [2, 3, 8] RETURN number

##### 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 3.16. Result
result

1 row

`["John","Bill"]`

Try this query live.  none WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names RETURN names[1..3] AS result

More details on lists can be found in Section 3.2.8.1, “Lists in general”.

#### 3.2.5.8. Property operators

 Since version 2.0, the previously supported property operators `?` and `!` have been removed. This syntax is no longer supported. Missing properties are now returned as `null`. Please use `(NOT(exists(.prop)) OR .prop=)` if you really need the old behavior of the `?` operator. — Also, the use of `?` for optional relationships has been removed in favor of the newly-introduced `OPTIONAL MATCH` clause.

#### 3.2.5.9. Equality and comparison of values

##### Equality

Cypher supports comparing values (see Section 3.2.1, “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 is `null`. This includes `null = null` and `null <> null`. The only way to reliably test if a value `v` is `null` is by using the special `v IS NULL`, or `v 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.

#### 3.2.5.10. 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`.
• Comparing for ordering when one argument is `null` (e.g. `null < 3` is `null`).
• It is an error to compare other types of values with each other for ordering.

#### 3.2.5.11. 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``

For other comparison operators, see Section 3.2.5.4, “Comparison operators”.