Add CIDR function to PPL (#3036)

core/build.gradle

@@ -57,6 +57,7 @@ dependencies {
     api group: 'com.google.code.gson', name: 'gson', version: '2.8.9'
     api group: 'com.tdunning', name: 't-digest', version: '3.3'
     api project(':common')
+    implementation "com.github.seancfoley:ipaddress:5.4.2"
 
     testImplementation('org.junit.jupiter:junit-jupiter:5.9.3')
     testImplementation group: 'org.hamcrest', name: 'hamcrest-library', version: '2.1'

core/src/main/java/org/opensearch/sql/exception/QueryEngineException.java

@@ -11,4 +11,8 @@ public class QueryEngineException extends RuntimeException {
   public QueryEngineException(String message) {
     super(message);
   }
+
+  public QueryEngineException(String message, Throwable cause) {
+    super(message, cause);
+  }
 }

core/src/main/java/org/opensearch/sql/exception/SemanticCheckException.java

@@ -7,7 +7,12 @@
 
 /** Semantic Check Exception. */
 public class SemanticCheckException extends QueryEngineException {
+
   public SemanticCheckException(String message) {
     super(message);
   }
+
+  public SemanticCheckException(String message, Throwable cause) {
+    super(message, cause);
+  }
 }

core/src/main/java/org/opensearch/sql/expression/DSL.java

@@ -563,6 +563,10 @@ public static FunctionExpression regexp(Expression... expressions) {
     return compile(FunctionProperties.None, BuiltinFunctionName.REGEXP, expressions);
   }
 
+  public static FunctionExpression cidrmatch(Expression... expressions) {
+    return compile(FunctionProperties.None, BuiltinFunctionName.CIDRMATCH, expressions);
+  }
+
   public static FunctionExpression concat(Expression... expressions) {
     return compile(FunctionProperties.None, BuiltinFunctionName.CONCAT, expressions);
   }

core/src/main/java/org/opensearch/sql/expression/function/BuiltinFunctionName.java

@@ -132,6 +132,9 @@ public enum BuiltinFunctionName {
   /** Text Functions. */
   TOSTRING(FunctionName.of("tostring")),
 
+  /** IP Functions. */
+  CIDRMATCH(FunctionName.of("cidrmatch")),
+
   /** Arithmetic Operators. */
   ADD(FunctionName.of("+")),
   ADDFUNCTION(FunctionName.of("add")),

core/src/main/java/org/opensearch/sql/expression/function/BuiltinFunctionRepository.java

@@ -27,6 +27,7 @@
 import org.opensearch.sql.expression.aggregation.AggregatorFunction;
 import org.opensearch.sql.expression.datetime.DateTimeFunction;
 import org.opensearch.sql.expression.datetime.IntervalClause;
+import org.opensearch.sql.expression.ip.IPFunction;
 import org.opensearch.sql.expression.operator.arthmetic.ArithmeticFunction;
 import org.opensearch.sql.expression.operator.arthmetic.MathematicalFunction;
 import org.opensearch.sql.expression.operator.convert.TypeCastOperator;
@@ -81,6 +82,7 @@ public static synchronized BuiltinFunctionRepository getInstance() {
       TypeCastOperator.register(instance);
       SystemFunctions.register(instance);
       OpenSearchFunctions.register(instance);
+      IPFunction.register(instance);
     }
     return instance;
   }

core/src/main/java/org/opensearch/sql/expression/function/DefaultFunctionResolver.java

@@ -61,7 +61,7 @@ public Pair<FunctionSignature, FunctionBuilder> resolve(FunctionSignature unreso
         && !FunctionSignature.isVarArgFunction(bestMatchEntry.getValue().getParamTypeList())) {
       throw new ExpressionEvaluationException(
           String.format(
-              "%s function expected %s, but get %s",
+              "%s function expected %s, but got %s",
               functionName,
               formatFunctions(functionBundle.keySet()),
               unresolvedSignature.formatTypes()));

core/src/main/java/org/opensearch/sql/expression/ip/IPFunction.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.expression.ip;
+
+import static org.opensearch.sql.data.type.ExprCoreType.BOOLEAN;
+import static org.opensearch.sql.data.type.ExprCoreType.STRING;
+import static org.opensearch.sql.expression.function.FunctionDSL.define;
+import static org.opensearch.sql.expression.function.FunctionDSL.impl;
+import static org.opensearch.sql.expression.function.FunctionDSL.nullMissingHandling;
+
+import inet.ipaddr.AddressStringException;
+import inet.ipaddr.IPAddressString;
+import inet.ipaddr.IPAddressStringParameters;
+import lombok.experimental.UtilityClass;
+import org.opensearch.sql.data.model.ExprValue;
+import org.opensearch.sql.data.model.ExprValueUtils;
+import org.opensearch.sql.exception.SemanticCheckException;
+import org.opensearch.sql.expression.function.BuiltinFunctionName;
+import org.opensearch.sql.expression.function.BuiltinFunctionRepository;
+import org.opensearch.sql.expression.function.DefaultFunctionResolver;
+
+/** Utility class that defines and registers IP functions. */
+@UtilityClass
+public class IPFunction {
+
+  public void register(BuiltinFunctionRepository repository) {
+    repository.register(cidrmatch());
+  }
+
+  private DefaultFunctionResolver cidrmatch() {
+
+    // TODO #3145: Add support for IP address data type.
+    return define(
+        BuiltinFunctionName.CIDRMATCH.getName(),
+        impl(nullMissingHandling(IPFunction::exprCidrMatch), BOOLEAN, STRING, STRING));
+  }
+
+  /**
+   * Returns whether the given IP address is within the specified CIDR IP address range. Supports
+   * both IPv4 and IPv6 addresses.
+   *
+   * @param addressExprValue IP address (e.g. "198.51.100.14" or "2001:0db8::ff00:42:8329").
+   * @param rangeExprValue IP address range in CIDR notation (e.g. "198.51.100.0/24" or
+   *     "2001:0db8::/32")
+   * @return true if the address is in the range; otherwise false.
+   * @throws SemanticCheckException if the address or range is not valid, or if they do not use the
+   *     same version (IPv4 or IPv6).
+   */
+  private ExprValue exprCidrMatch(ExprValue addressExprValue, ExprValue rangeExprValue) {
+
+    String addressString = addressExprValue.stringValue();
+    String rangeString = rangeExprValue.stringValue();
+
+    final IPAddressStringParameters validationOptions =
+        new IPAddressStringParameters.Builder()
+            .allowEmpty(false)
+            .setEmptyAsLoopback(false)
+            .allow_inet_aton(false)
+            .allowSingleSegment(false)
+            .toParams();
+
+    // Get and validate IP address.
+    IPAddressString address =
+        new IPAddressString(addressExprValue.stringValue(), validationOptions);
+
+    try {
+      address.validate();
+    } catch (AddressStringException e) {
+      String msg =
+          String.format(
+              "IP address '%s' is not valid. Error details: %s", addressString, e.getMessage());
+      throw new SemanticCheckException(msg, e);
+    }
+
+    // Get and validate CIDR IP address range.
+    IPAddressString range = new IPAddressString(rangeExprValue.stringValue(), validationOptions);
+
+    try {
+      range.validate();
+    } catch (AddressStringException e) {
+      String msg =
+          String.format(
+              "CIDR IP address range '%s' is not valid. Error details: %s",
+              rangeString, e.getMessage());
+      throw new SemanticCheckException(msg, e);
+    }
+
+    // Address and range must use the same IP version (IPv4 or IPv6).
+    if (address.isIPv4() ^ range.isIPv4()) {
+      String msg =
+          String.format(
+              "IP address '%s' and CIDR IP address range '%s' are not compatible. Both must be"
+                  + " either IPv4 or IPv6.",
+              addressString, rangeString);
+      throw new SemanticCheckException(msg);
+    }
+
+    return ExprValueUtils.booleanValue(range.contains(address));
+  }
+}

core/src/main/java/org/opensearch/sql/expression/operator/predicate/UnaryPredicateOperator.java

@@ -111,8 +111,7 @@ private static DefaultFunctionResolver ifFunction() {
                 .map(v -> impl((UnaryPredicateOperator::exprIf), v, BOOLEAN, v, v))
                 .collect(Collectors.toList());
 
-    DefaultFunctionResolver functionResolver = FunctionDSL.define(functionName, functionsOne);
-    return functionResolver;
+    return FunctionDSL.define(functionName, functionsOne);
   }
 
   private static DefaultFunctionResolver ifNull() {
@@ -128,40 +127,37 @@ private static DefaultFunctionResolver ifNull() {
                 .map(v -> impl((UnaryPredicateOperator::exprIfNull), v, v, v))
                 .collect(Collectors.toList());
 
-    DefaultFunctionResolver functionResolver = FunctionDSL.define(functionName, functionsOne);
-    return functionResolver;
+    return FunctionDSL.define(functionName, functionsOne);
   }
 
   private static DefaultFunctionResolver nullIf() {
     FunctionName functionName = BuiltinFunctionName.NULLIF.getName();
     List<ExprCoreType> typeList = ExprCoreType.coreTypes();
 
-    DefaultFunctionResolver functionResolver =
-        FunctionDSL.define(
-            functionName,
-            typeList.stream()
-                .map(v -> impl((UnaryPredicateOperator::exprNullIf), v, v, v))
-                .collect(Collectors.toList()));
-    return functionResolver;
+    return FunctionDSL.define(
+        functionName,
+        typeList.stream()
+            .map(v -> impl((UnaryPredicateOperator::exprNullIf), v, v, v))
+            .collect(Collectors.toList()));
   }
 
   /**
    * v2 if v1 is null.
    *
-   * @param v1 varable 1
-   * @param v2 varable 2
+   * @param v1 variable 1
+   * @param v2 variable 2
    * @return v2 if v1 is null
    */
   public static ExprValue exprIfNull(ExprValue v1, ExprValue v2) {
     return (v1.isNull() || v1.isMissing()) ? v2 : v1;
   }
 
   /**
-   * return null if v1 equls to v2.
+   * return null if v1 equals to v2.
    *
-   * @param v1 varable 1
-   * @param v2 varable 2
-   * @return null if v1 equls to v2
+   * @param v1 variable 1
+   * @param v2 variable 2
+   * @return null if v1 equals to v2
    */
   public static ExprValue exprNullIf(ExprValue v1, ExprValue v2) {
     return v1.equals(v2) ? LITERAL_NULL : v1;

core/src/test/java/org/opensearch/sql/analysis/AnalyzerTest.java

@@ -158,7 +158,7 @@ public void filter_relation_with_invalid_qualifiedName_ExpressionEvaluationExcep
         "= function expected {[BYTE,BYTE],[SHORT,SHORT],[INTEGER,INTEGER],[LONG,LONG],"
             + "[FLOAT,FLOAT],[DOUBLE,DOUBLE],[STRING,STRING],[BOOLEAN,BOOLEAN],[DATE,DATE],"
             + "[TIME,TIME],[TIMESTAMP,TIMESTAMP],[INTERVAL,INTERVAL],"
-            + "[STRUCT,STRUCT],[ARRAY,ARRAY]}, but get [STRING,INTEGER]",
+            + "[STRUCT,STRUCT],[ARRAY,ARRAY]}, but got [STRING,INTEGER]",
         exception.getMessage());
   }
 

core/src/test/java/org/opensearch/sql/expression/aggregation/PercentileApproxAggregatorTest.java

@@ -13,11 +13,18 @@
 
 package org.opensearch.sql.expression.aggregation;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.when;
-import static org.opensearch.sql.data.model.ExprValueUtils.*;
-import static org.opensearch.sql.data.type.ExprCoreType.*;
+import static org.opensearch.sql.data.model.ExprValueUtils.integerValue;
+import static org.opensearch.sql.data.model.ExprValueUtils.longValue;
+import static org.opensearch.sql.data.type.ExprCoreType.DOUBLE;
+import static org.opensearch.sql.data.type.ExprCoreType.FLOAT;
+import static org.opensearch.sql.data.type.ExprCoreType.INTEGER;
+import static org.opensearch.sql.data.type.ExprCoreType.LONG;
+import static org.opensearch.sql.data.type.ExprCoreType.STRING;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -195,7 +202,7 @@ public void test_percentile_with_invalid_size() {
         "percentile_approx function expected"
             + " {[INTEGER,DOUBLE],[INTEGER,DOUBLE,DOUBLE],[LONG,DOUBLE],[LONG,DOUBLE,DOUBLE],"
             + "[FLOAT,DOUBLE],[FLOAT,DOUBLE,DOUBLE],[DOUBLE,DOUBLE],[DOUBLE,DOUBLE,DOUBLE]},"
-            + " but get [DOUBLE,STRING]",
+            + " but got [DOUBLE,STRING]",
         exception2.getMessage());
   }
 

core/src/test/java/org/opensearch/sql/expression/datetime/DateAddAndAddDateTest.java

@@ -156,7 +156,7 @@ public void adddate_has_second_signature_but_not_date_add() {
             () -> date_add(LocalDateTime.of(1961, 4, 12, 9, 7), 100500));
     assertEquals(
         "date_add function expected {[DATE,INTERVAL],[TIMESTAMP,INTERVAL],"
-            + "[TIME,INTERVAL]}, but get [TIMESTAMP,INTEGER]",
+            + "[TIME,INTERVAL]}, but got [TIMESTAMP,INTEGER]",
         exception.getMessage());
   }
 

core/src/test/java/org/opensearch/sql/expression/datetime/DateSubAndSubDateTest.java

@@ -139,7 +139,7 @@ public void subdate_has_second_signature_but_not_date_sub() {
             ExpressionEvaluationException.class,
             () -> date_sub(LocalDateTime.of(1961, 4, 12, 9, 7), 100500));
     assertEquals(
-        "date_sub function expected {[DATE,INTERVAL],[TIMESTAMP,INTERVAL],[TIME,INTERVAL]}, but get"
+        "date_sub function expected {[DATE,INTERVAL],[TIMESTAMP,INTERVAL],[TIME,INTERVAL]}, but got"
             + " [TIMESTAMP,INTEGER]",
         exception.getMessage());
   }

core/src/test/java/org/opensearch/sql/expression/function/DefaultFunctionResolverTest.java

@@ -72,7 +72,7 @@ void resolve_function_not_match() {
         assertThrows(
             ExpressionEvaluationException.class, () -> resolver.resolve(functionSignature));
     assertEquals(
-        "add function expected {[INTEGER,INTEGER]}, but get [BOOLEAN,BOOLEAN]",
+        "add function expected {[INTEGER,INTEGER]}, but got [BOOLEAN,BOOLEAN]",
         exception.getMessage());
   }