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;
+ }
+}