Operators

The operators are grouped by category. Most of them return a null value if any operand has a null value. Anyway, there are some exceptions. So, for each operator, the behavior in case of a null value operand is specified.

Comparison operators

Comparison operators are binary operators that return a Boolean or a null value as results. They are mostly used in the WHERE clause (see Chapter 2, Filter, Aggregate, and Combine Results, for details) to filter data according to a condition, although they can be used in the RETURN clause as well.

In Cypher, comparison operators can be grouped in two classes: ordering operators and equality operators.

Ordering operators

Ordering operators are used to compare values (usually property values or literals). They are as follows:

Operator	Description
<	Less than
<=	Less than or equal to
>	Greater than
>=	Greater than or equal to

Let's see an example using one of these operators. This query looks for all books published in 2012 or later. If a PublishedBy relationship doesn't have the year property set, it will be discarded. The query is as follows:

MATCH (a:Book)-[r:PublishedBy]-(b:Publisher) 
WHERE r.year >= 2012 
RETURN a,r,b

Note the following outcomes:

• Only numbers and string values are supported.

• Comparing any value to a null value will result in a null value. For example, all of the following expressions will give a null value:

  • 1 < NULL

  • NULL < "String"

  • NULL < NULL

• Comparing nodes or relationships is an illegal operation. It will result in a syntax error.

• Comparing numbers of different types (a double value with an integer value or a long value with an integer value) is supported; however, numbers will be converted before being compared.

• Comparing arrays is not supported.

• Comparing numbers to string values will generate a runtime error. If you don't know whether a property is a number in the dataset and if a string comparison is enough, you can resort to the STR function (this is covered later in this appendix).

Equality operators

Equality operators are used to test the equality of two values. They return a Boolean value or a null value. They are as follows:

• = returns true if the two values are equal

• <> returns true if the two values are not equal

The following query returns the books that have the specified title:

MATCH (a:Book) 
WHERE a.title = "Learning Cypher" 
RETURN a

Note the following:

• Comparing any value to a null value will result in a null value. To test null values, use the NULL equality operators mentioned in the next section. For example, all of the following expressions will give a null value as the result:

  • 230.0 = NULL

  • NULL = "String"

  • NULL = NULL

• Comparing values of properties of different types is supported and will always return false, except for the numbers that will be converted before the comparison.

  Tip

  Because of this important difference with ordering operators, changing from an equality operator to a sorting operator and vice versa should be done carefully in order to avoid unexpected results.

• String comparison is case sensitive.

• Nodes, relationships, and paths can be compared for equality as well, as explained in the following list:

  • Two nodes are equal only if they are the same node

  • Two relationships are equal only if they are the same relationship

  • Two paths are equal only if they contain both the same nodes and the same relationships

• Comparing either a node, a relationship, or a path to a property value (number or string) will generate a syntax error.

NULL equality operators

The operators IS NULL and IS NOT NULL are used to check whether a value is a null value. These operators always return a Boolean value. They are mostly used to check whether or not a property is set in a node or in a relationship. The following query returns all books that have a title property:

MATCH (b:Book) 
WHERE b.title IS NOT NULL 
RETURN b

All values can be tested; not only node properties and relationship properties but also nodes, relationships, and paths.

Mathematical operators

Mathematical operators work with number values. They are binary operators except the unary minus (-). The binary operators are +, -, *, /, %, and ^. Consider the following query:

MATCH (a)-[r:PublishedBy]-(b) 
WHERE r.year % 2 = 1 
RETURN -2^ 1.0 * COUNT(DISTINCT a) / COUNT(DISTINCT b)

This query performs an example mathematical operation on the number of distinct books per publisher.

Note the following:

• Every operator will return a null value if any operand is a NULL value. Refer to the COALESCE function, described in a later section, to deal with the default values in case of a null value.

• Every operator will throw an exception if any operand is not a number, except for the + operator. This also holds true for strings and collections, but with a different meaning (see the next section).

The concatenation operator

Both strings and collections have the + operator. It is used to concatenate items to strings and collections. Consider the following query:

RETURN "Hello" + " Cypher " + 2

This simple query just concatenates some strings. The number 2 is converted to string just before being concatenated. Now consider the following query:

MATCH (aa:Book) 
RETURN aa.tags + ["book","found"]

This query, for each book in the database, returns a collection computed by concatenating the book's tags with a fixed collection of tags.

Note the following:

• This operator returns a null value if any operand is a null value.

• When concatenating strings, the + operator will try to convert the operand to string, except when an operand is a collection. In this case, the result will be in a new collection with the string concatenated.

The IN operator

The IN predicate is used to check whether a given value is in a collection of items. It returns either a Boolean value or a null value if any operand has a null value. Consider the following query:

MATCH (aa:Book) 
WHERE 'drama' IN (aa.tags) 
RETURN aa.title

This query returns all books that have the word drama in their tags.

Regular expressions

To check whether a string value matches a regular expression, use the =~ operator. This operator is explained in detail in Chapter 2, Filter, Aggregate, and Combine Results. As a reminder, following is an example query that looks for books that contain the word tale:

MATCH (aa:Book) 
WHERE aa.title =~ "(?i).*tale.*" 
RETURN aa