SQL: Implement null safe equality operator <=> (#35873)

This operator handles nulls in different way than the normal `=`.
If one of the operants is `null` and the other not it returns `false`.
If both operants are `null` it returns `true`. Therefore in contrary to
`=`, which returns `null` if at least one of the operants is `null`, this one
never returns `null` as a result.

Closes: #35871

Author: matriv

docs/reference/sql/functions/operators.asciidoc

@@ -12,7 +12,19 @@ Boolean operator for comparing against one or multiple expressions.
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldEquality]
 --------------------------------------------------
 
-* Inequality (`<>` or `!=` or `<=>`)
+* Null safe Equality (`<=>`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[nullEqualsCompareWithNull]
+--------------------------------------------------
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[nullEqualsCompareTwoNulls]
+--------------------------------------------------
+
+* Inequality (`<>` or `!=`)
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------

x-pack/plugin/sql/qa/src/main/resources/agg.csv-spec

@@ -136,4 +136,4 @@ null           |null           |null           |null           |null           |
 2              |2              |38             |2              |2.0            |100.0          |NaN            |NaN            
 3              |3              |51             |3              |3.0            |100.0          |NaN            |NaN            
 4              |4              |72             |4              |4.0            |0.0            |NaN            |NaN   
-;
+;

x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec

@@ -1619,3 +1619,23 @@ SELECT NULLIF('elastic', 'elastic') AS "nullif";
 null
 // end::nullIfReturnNull
 ;
+
+nullEqualsCompareWithNull
+// tag::nullEqualsCompareWithNull
+SELECT 'elastic' <=> null AS "equals";
+
+    equals
+---------------
+false
+// end::nullEqualsCompareWithNull
+;
+
+nullEqualsCompareTwoNulls
+// tag::nullEqualsCompareTwoNulls
+SELECT null <=> null AS "equals";
+
+    equals
+---------------
+true
+// end::nullEqualsCompareTwoNulls
+;

x-pack/plugin/sql/src/main/antlr/SqlBase.g4

@@ -277,7 +277,7 @@ constant
     ;
 
 comparisonOperator
-    : EQ | NEQ | LT | LTE | GT | GTE
+    : EQ | NULLEQ | NEQ | LT | LTE | GT | GTE
     ;
 
 booleanValue
@@ -452,7 +452,8 @@ GUID_ESC: '{GUID';
 ESC_END: '}';
 
 EQ  : '=';
-NEQ : '<>' | '!=' | '<=>';
+NULLEQ: '<=>';
+NEQ : '<>' | '!=';
 LT  : '<';
 LTE : '<=';
 GT  : '>';

x-pack/plugin/sql/src/main/antlr/SqlBase.tokens

@@ -96,32 +96,33 @@ TIMESTAMP_ESC=95
 GUID_ESC=96
 ESC_END=97
 EQ=98
-NEQ=99
-LT=100
-LTE=101
-GT=102
-GTE=103
-PLUS=104
-MINUS=105
-ASTERISK=106
-SLASH=107
-PERCENT=108
-CONCAT=109
-DOT=110
-PARAM=111
-STRING=112
-INTEGER_VALUE=113
-DECIMAL_VALUE=114
-IDENTIFIER=115
-DIGIT_IDENTIFIER=116
-TABLE_IDENTIFIER=117
-QUOTED_IDENTIFIER=118
-BACKQUOTED_IDENTIFIER=119
-SIMPLE_COMMENT=120
-BRACKETED_COMMENT=121
-WS=122
-UNRECOGNIZED=123
-DELIMITER=124
+NULLEQ=99
+NEQ=100
+LT=101
+LTE=102
+GT=103
+GTE=104
+PLUS=105
+MINUS=106
+ASTERISK=107
+SLASH=108
+PERCENT=109
+CONCAT=110
+DOT=111
+PARAM=112
+STRING=113
+INTEGER_VALUE=114
+DECIMAL_VALUE=115
+IDENTIFIER=116
+DIGIT_IDENTIFIER=117
+TABLE_IDENTIFIER=118
+QUOTED_IDENTIFIER=119
+BACKQUOTED_IDENTIFIER=120
+SIMPLE_COMMENT=121
+BRACKETED_COMMENT=122
+WS=123
+UNRECOGNIZED=124
+DELIMITER=125
 '('=1
 ')'=2
 ','=3
@@ -220,15 +221,16 @@ DELIMITER=124
 '{GUID'=96
 '}'=97
 '='=98
-'<'=100
-'<='=101
-'>'=102
-'>='=103
-'+'=104
-'-'=105
-'*'=106
-'/'=107
-'%'=108
-'||'=109
-'.'=110
-'?'=111
+'<=>'=99
+'<'=101
+'<='=102
+'>'=103
+'>='=104
+'+'=105
+'-'=106
+'*'=107
+'/'=108
+'%'=109
+'||'=110
+'.'=111
+'?'=112

x-pack/plugin/sql/src/main/antlr/SqlBaseLexer.tokens

@@ -96,31 +96,32 @@ TIMESTAMP_ESC=95
 GUID_ESC=96
 ESC_END=97
 EQ=98
-NEQ=99
-LT=100
-LTE=101
-GT=102
-GTE=103
-PLUS=104
-MINUS=105
-ASTERISK=106
-SLASH=107
-PERCENT=108
-CONCAT=109
-DOT=110
-PARAM=111
-STRING=112
-INTEGER_VALUE=113
-DECIMAL_VALUE=114
-IDENTIFIER=115
-DIGIT_IDENTIFIER=116
-TABLE_IDENTIFIER=117
-QUOTED_IDENTIFIER=118
-BACKQUOTED_IDENTIFIER=119
-SIMPLE_COMMENT=120
-BRACKETED_COMMENT=121
-WS=122
-UNRECOGNIZED=123
+NULLEQ=99
+NEQ=100
+LT=101
+LTE=102
+GT=103
+GTE=104
+PLUS=105
+MINUS=106
+ASTERISK=107
+SLASH=108
+PERCENT=109
+CONCAT=110
+DOT=111
+PARAM=112
+STRING=113
+INTEGER_VALUE=114
+DECIMAL_VALUE=115
+IDENTIFIER=116
+DIGIT_IDENTIFIER=117
+TABLE_IDENTIFIER=118
+QUOTED_IDENTIFIER=119
+BACKQUOTED_IDENTIFIER=120
+SIMPLE_COMMENT=121
+BRACKETED_COMMENT=122
+WS=123
+UNRECOGNIZED=124
 '('=1
 ')'=2
 ','=3
@@ -219,15 +220,16 @@ UNRECOGNIZED=123
 '{GUID'=96
 '}'=97
 '='=98
-'<'=100
-'<='=101
-'>'=102
-'>='=103
-'+'=104
-'-'=105
-'*'=106
-'/'=107
-'%'=108
-'||'=109
-'.'=110
-'?'=111
+'<=>'=99
+'<'=101
+'<='=102
+'>'=103
+'>='=104
+'+'=105
+'-'=106
+'*'=107
+'/'=108
+'%'=109
+'||'=110
+'.'=111
+'?'=112

x-pack/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/whitelist/InternalSqlScriptUtils.java

@@ -92,6 +92,10 @@ public static Boolean eq(Object left, Object right) {
         return BinaryComparisonOperation.EQ.apply(left, right);
     }
 
+    public static Boolean nulleq(Object left, Object right) {
+        return BinaryComparisonOperation.NULLEQ.apply(left, right);
+    }
+
     public static Boolean neq(Object left, Object right) {
         return BinaryComparisonOperation.NEQ.apply(left, right);
     }

x-pack/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/predicate/operator/comparison/BinaryComparisonProcessor.java

@@ -15,10 +15,11 @@
 import java.util.function.BiFunction;
 
 public class BinaryComparisonProcessor extends FunctionalBinaryProcessor<Object, Object, Boolean, BinaryComparisonOperation> {
-    
+
     public enum BinaryComparisonOperation implements PredicateBiFunction<Object, Object, Boolean> {
 
         EQ(Comparisons::eq, "=="),
+        NULLEQ(Comparisons::nulleq, "<=>"),
         NEQ(Comparisons::neq, "!="),
         GT(Comparisons::gt, ">"),
         GTE(Comparisons::gte, ">="),
@@ -38,6 +39,14 @@ public String symbol() {
             return symbol;
         }
 
+        @Override
+        public Boolean apply(Object left, Object right) {
+            if (this != NULLEQ && (left == null || right == null)) {
+                return null;
+            }
+            return doApply(left, right);
+        }
+
         @Override
         public final Boolean doApply(Object left, Object right) {
             return process.apply(left, right);
@@ -48,7 +57,7 @@ public String toString() {
             return symbol;
         }
     }
-    
+
     public static final String NAME = "cb";
 
     public BinaryComparisonProcessor(Processor left, Processor right, BinaryComparisonOperation operation) {
@@ -63,4 +72,12 @@ public BinaryComparisonProcessor(StreamInput in) throws IOException {
     public String getWriteableName() {
         return NAME;
     }
+
+    @Override
+    public Object process(Object input) {
+        if (function() == BinaryComparisonOperation.NULLEQ) {
+            return doProcess(left().process(input), right().process(input));
+        }
+        return super.process(input);
+    }
 }

x-pack/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/predicate/operator/comparison/Comparisons.java

@@ -19,6 +19,14 @@ public static Boolean eq(Object l, Object r) {
         return i == null ? null : i.intValue() == 0;
     }
 
+    public static boolean nulleq(Object l, Object r) {
+        if (l == null && r == null) {
+            return true;
+        }
+        Integer i = compare(l, r);
+        return i == null ? false : i.intValue() == 0;
+    }
+
     static Boolean neq(Object l, Object r) {
         Integer i = compare(l, r);
         return i == null ? null : i.intValue() != 0;

x-pack/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/predicate/operator/comparison/NullEquals.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+package org.elasticsearch.xpack.sql.expression.predicate.operator.comparison;
+
+import org.elasticsearch.xpack.sql.expression.Expression;
+import org.elasticsearch.xpack.sql.expression.predicate.operator.comparison.BinaryComparisonProcessor.BinaryComparisonOperation;
+import org.elasticsearch.xpack.sql.tree.Location;
+import org.elasticsearch.xpack.sql.tree.NodeInfo;
+
+/**
+ * Implements the MySQL {@code <=>} operator
+ */
+public class NullEquals extends BinaryComparison {
+
+    public NullEquals(Location location, Expression left, Expression right) {
+        super(location, left, right, BinaryComparisonOperation.NULLEQ);
+    }
+
+    @Override
+    protected NodeInfo<NullEquals> info() {
+        return NodeInfo.create(this, NullEquals::new, left(), right());
+    }
+
+    @Override
+    protected NullEquals replaceChildren(Expression newLeft, Expression newRight) {
+        return new NullEquals(location(), newLeft, newRight);
+    }
+
+    @Override
+    public NullEquals swapLeftAndRight() {
+        return new NullEquals(location(), right(), left());
+    }
+
+    @Override
+    public boolean nullable() {
+        return false;
+    }
+}