3.2.14. Working with null

3.2.14. Working with `null`

Introduction to null in Cypher
Logical operations with null
The IN operator and null
The [] operator and null
Expressions that return null

3.2.14.1. Introduction to `null` in Cypher

In Cypher, null is used to represent missing or undefined values. Conceptually, null means 'a missing unknown value' and it is treated somewhat differently from other values. For example getting a property from a node that does not have said property produces null. Most expressions that take null as input will produce null. This includes boolean expressions that are used as predicates in the WHERE clause. In this case, anything that is not true is interpreted as being false.

null is not equal to null. Not knowing two values does not imply that they are the same value. So the expression null = null yields null and not true.

3.2.14.2. Logical operations with `null`

The logical operators (AND, OR, XOR, NOT) treat null as the 'unknown' value of three-valued logic.

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`

3.2.14.3. The `IN` operator and `null`

The IN operator follows similar logic. If Cypher knows that something exists in a list, the result will be true. Any list that contains a null and doesn’t have a matching element will return null. Otherwise, the result will be false. Here is a table with examples:

Expression	Result
2 IN [1, 2, 3]	`true`
2 IN [1, `null`, 3]	`null`
2 IN [1, 2, `null`]	`true`
2 IN [1]	`false`
2 IN []	`false`
`null` IN [1, 2, 3]	`null`
`null` IN [1, `null`, 3]	`null`
`null` IN []	`false`

Using all, any, none, and single follows a similar rule. If the result can be calculated definitely, true or false is returned. Otherwise null is produced.

3.2.14.4. The `[]` operator and `null`

Accessing a list or a map with null will result in null:

Expression	Result
[1, 2, 3][`null`]	`null`
[1, 2, 3, 4][`null`..2]	`null`
[1, 2, 3][1..`null`]	`null`
{age: 25}[`null`]	`null`

Using parameters to pass in the bounds, such as a[$lower..$upper], may result in a null for the lower or upper bound (or both). The following workaround will prevent this from happening by setting the absolute minimum and maximum bound values:

a[coalesce($lower,0)..coalesce($upper,size(a))]

3.2.14.5. Expressions that return `null`

Getting a missing element from a list: [][0], head([])
Trying to access a property that does not exist on a node or relationship: n.missingProperty
Comparisons when either side is null: 1 < null
Arithmetic expressions containing null: 1 + null
Function calls where any arguments are null: sin(null)