[DOC-9906] IS DISTINCT FROM Operator

modules/n1ql/pages/n1ql-language-reference/comparisonops.adoc

@@ -119,7 +119,7 @@ include::partial$grammar/n1ql.ebnf[tag=is-expr]
 
 image::n1ql-language-reference/is-expr.png["Syntax diagram", align=left]
 
-[cols="100,326,213"]
+[cols="1a,3a,2a"]
 |===
 | Operator | Description | Returns
 
@@ -158,8 +158,34 @@ Equivalent to IS NOT VALUED/IS NOT KNOWN.
 | Value for field is known. Value is neither NULL nor missing. +
 Equivalent to IS VALUED/IS KNOWN. 
 | TRUE OR FALSE
+
+| IS DISTINCT FROM
+| Compares two values to determine if they're distinct. 
+| TRUE or FALSE +
+
+--
+* TRUE if one value is NULL and the other is non-NULL.
+* FALSE if both values are NULL.
+* MISSING if either value is MISSING.
+* The result of the comparison `expr != expr` if both values are non-NULL and non-MISSING.
+--
+
+| IS NOT DISTINCT FROM
+| Compares two values to determine if they're not distinct. 
+
+| TRUE or FALSE +
+
+--
+* FALSE if one value is NULL and the other is non-NULL.
+* TRUE if both values are NULL.
+* MISSING if either value is MISSING.
+* The result of the comparison `expr == expr` if both values are non-NULL and non-MISSING.
+--  
+
 |===
 
+=== Examples
+
 .IS NULL
 ====
 .Query
@@ -241,6 +267,44 @@ SELECT NULL IS UNKNOWN,
 ----
 ====
 
+.IS DISTINCT FROM
+====
+
+.Query
+[source,sqlpp]
+----
+SELECT 1 IS DISTINCT FROM 1,
+       1 IS DISTINCT FROM 2,
+       NULL IS DISTINCT FROM NULL,
+       NULL IS DISTINCT FROM 1,
+       1 IS DISTINCT FROM MISSING,
+       1 IS NOT DISTINCT FROM 1,
+       1 IS NOT DISTINCT FROM 2,
+       NULL IS NOT DISTINCT FROM NULL,
+       NULL IS NOT DISTINCT FROM 1,
+       1 IS NOT DISTINCT FROM MISSING;
+----
+
+.Returns
+[source,json]
+----
+[
+  {
+    "$1": false,
+    "$2": true,
+    "$3": false,
+    "$4": true,
+    "$5": true,
+    "$6": true,
+    "$7": false,
+    "$8": true,
+    "$9": false,
+    "$10": false
+  }
+]
+----
+====
+
 == Comparison of Data Types
 
 === Strings

modules/n1ql/partials/grammar/n1ql.ebnf

@@ -150,7 +150,8 @@ like-expr ::= expr 'NOT'? 'LIKE' expr
 is-expr ::= expr 'IS' 'NOT'? 'NULL' |
             expr 'IS' 'NOT'? 'MISSING' |
             expr 'IS' 'NOT'? 'VALUED' |
-            expr 'IS' 'NOT'? 'UNKNOWN'
+            expr 'IS' 'NOT'? 'UNKNOWN' |
+            expr 'IS' 'NOT'? 'DISTINCT' 'FROM' expr
 /* end::is-expr[] */