Fail fast when relevance functions cannot be pushed down

Relevance search functions (match, match_phrase, query_string, ...) are
Calcite marker UDFs with no executable implementation -- they exist only
to be rewritten into an OpenSearch query during push down. Nothing
guaranteed that rewrite happened, and the two script fallbacks in
PredicateAnalyzer would serialize whatever they could not analyze into a
Calcite script, including a relevance call. That script was then shipped
to every data node, where code generation hit RelevanceQueryImplementor
and failed, surfacing to the user as:

  QueryShardException[failed to create query: Failed to compile inline
  script [...]]  -> 500, all shards failed

Guard both fallbacks so a node containing a relevance function is never
serialized into a script, and report it on the coordinator instead.

Also:
- Reject a non-indexed field or non-literal query operand in
  visitRelevanceFunc as PredicateAnalyzerException rather than letting an
  unchecked ClassCastException escape to the top-level Throwable catch,
  which was one route into the script fallback.
- Give the last-resort UnsupportedOperationException an actionable
  message naming the function and the constraint, instead of only
  "only supported when they are pushed down".
- Hoist the relevance-function detection out of
  RelevanceFunctionPushdownRule into UserDefinedFunctionUtils so the
  analyzer and the rule share one definition.

Queries that legitimately push down are unaffected; the reported
combination of match() with a like() filter keeps working, with the LIKE
going down as a script and the relevance call as a native match query.

Signed-off-by: Jialiang Liang <ryanleeang@gmail.com>

Author: RyanL1997

core/src/main/java/org/opensearch/sql/calcite/utils/UserDefinedFunctionUtils.java

@@ -17,6 +17,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Locale;
 import java.util.Objects;
 import java.util.Set;
 import javax.annotation.Nullable;
@@ -29,6 +30,7 @@
 import org.apache.calcite.rel.type.RelDataType;
 import org.apache.calcite.rex.RexCall;
 import org.apache.calcite.rex.RexNode;
+import org.apache.calcite.rex.RexVisitorImpl;
 import org.apache.calcite.schema.impl.AggregateFunctionImpl;
 import org.apache.calcite.sql.SqlAggFunction;
 import org.apache.calcite.sql.SqlIdentifier;
@@ -81,6 +83,76 @@ public class UserDefinedFunctionUtils {
       ImmutableSet.of("simple_query_string", "query_string", "multi_match");
   public static String IP_FUNCTION_NAME = "IP";
 
+  /** Returns true if the given operator name is a relevance search query function. */
+  public static boolean isRelevanceFunction(String operatorName) {
+    String lowerCased = operatorName.toLowerCase(Locale.ROOT);
+    return SINGLE_FIELD_RELEVANCE_FUNCTION_SET.contains(lowerCased)
+        || MULTI_FIELDS_RELEVANCE_FUNCTION_SET.contains(lowerCased);
+  }
+
+  /**
+   * Checks whether a {@link RexNode} tree contains a relevance search query function such as {@code
+   * match} or {@code query_string}.
+   *
+   * <p>Relevance functions have no executable implementation: they exist only as markers to be
+   * rewritten into an OpenSearch query during push down (see {@code RelevanceQueryFunction}).
+   * Callers must use this to avoid handing such a node to any execution path that would try to
+   * generate code for it -- notably script push down, where the failure would surface as a shard
+   * side "Failed to compile inline script" error instead of a local planning error.
+   *
+   * @param node the node to inspect
+   * @return true if the tree contains a relevance function
+   */
+  public static boolean containsRelevanceFunction(RexNode node) {
+    RelevanceFunctionFinder finder = new RelevanceFunctionFinder();
+    node.accept(finder);
+    return finder.found;
+  }
+
+  /** Visitor that detects relevance functions anywhere in a {@link RexNode} tree. */
+  private static class RelevanceFunctionFinder extends RexVisitorImpl<Void> {
+    private boolean found = false;
+
+    RelevanceFunctionFinder() {
+      super(true);
+    }
+
+    @Override
+    public Void visitCall(RexCall call) {
+      if (isRelevanceFunction(call.getOperator().getName())) {
+        found = true;
+        return null; // stop descending once found
+      }
+      return super.visitCall(call);
+    }
+  }
+
+  /**
+   * Returns the name of the first relevance function found in the tree, or null if there is none.
+   */
+  public static String findRelevanceFunctionName(RexNode node) {
+    RelevanceFunctionNameFinder finder = new RelevanceFunctionNameFinder();
+    node.accept(finder);
+    return finder.name;
+  }
+
+  private static class RelevanceFunctionNameFinder extends RexVisitorImpl<Void> {
+    private String name = null;
+
+    RelevanceFunctionNameFinder() {
+      super(true);
+    }
+
+    @Override
+    public Void visitCall(RexCall call) {
+      if (name == null && isRelevanceFunction(call.getOperator().getName())) {
+        name = call.getOperator().getName().toLowerCase(Locale.ROOT);
+        return null;
+      }
+      return super.visitCall(call);
+    }
+  }
+
   /**
    * Creates a SqlUserDefinedAggFunction that wraps a Java class implementing an aggregate function.
    *

core/src/main/java/org/opensearch/sql/expression/function/udf/RelevanceQueryFunction.java

@@ -7,6 +7,7 @@
 
 import com.google.common.collect.ImmutableList;
 import java.util.List;
+import java.util.Locale;
 import org.apache.calcite.adapter.enumerable.NotNullImplementor;
 import org.apache.calcite.adapter.enumerable.NullPolicy;
 import org.apache.calcite.adapter.enumerable.RexToLixTranslator;
@@ -94,8 +95,17 @@ public static class RelevanceQueryImplementor implements NotNullImplementor {
     @Override
     public Expression implement(
         RexToLixTranslator translator, RexCall call, List<Expression> translatedOperands) {
+      // Reaching code generation means the call was not rewritten into an OpenSearch query. There
+      // is no row-by-row implementation to fall back to, so report why rather than just that.
       throw new UnsupportedOperationException(
-          "Relevance search query functions are only supported when they are pushed down");
+          String.format(
+              Locale.ROOT,
+              "Relevance search function [%s] could not be pushed down to OpenSearch, and it has no"
+                  + " other execution path. Apply it directly to an indexed field before any"
+                  + " command that transforms rows (eval, parse, rex, stats, top, rare, sort, head,"
+                  + " lookup), and not to a column computed by the query itself. Expression: %s",
+              call.getOperator().getName().toLowerCase(Locale.ROOT),
+              call));
     }
   }
 }

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteRelevanceFunctionPushdownFailureIT.java

@@ -0,0 +1,150 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.calcite.remote;
+
+import static org.opensearch.sql.util.MatcherUtils.rows;
+import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
+import static org.opensearch.sql.util.TestUtils.createIndexByRestClient;
+import static org.opensearch.sql.util.TestUtils.getResponseBody;
+import static org.opensearch.sql.util.TestUtils.isIndexExist;
+import static org.opensearch.sql.util.TestUtils.performRequest;
+
+import java.io.IOException;
+import java.util.Locale;
+import org.json.JSONObject;
+import org.junit.Test;
+import org.opensearch.client.Request;
+import org.opensearch.client.ResponseException;
+import org.opensearch.sql.ppl.PPLIntegTestCase;
+
+/**
+ * Tests that relevance search functions which cannot be pushed down fail fast on the coordinator
+ * with an actionable message, instead of being serialized into a script that only fails when
+ * compiled on the shards.
+ *
+ * <p>Relevance functions have no row-by-row implementation -- they exist only to be rewritten into
+ * an OpenSearch query during push down. Before this fix, a query the analyzer could not handle was
+ * wrapped in a script and shipped to every data node, surfacing as {@code QueryShardException:
+ * Failed to compile inline script} with all shards failing.
+ */
+public class CalciteRelevanceFunctionPushdownFailureIT extends PPLIntegTestCase {
+
+  private static final String TEST_INDEX = "relevance_pushdown_failure";
+
+  @Override
+  public void init() throws Exception {
+    super.init();
+    enableCalcite();
+    createTestIndex();
+  }
+
+  private void createTestIndex() throws IOException {
+    if (isIndexExist(client(), TEST_INDEX)) {
+      return;
+    }
+    createIndexByRestClient(
+        client(),
+        TEST_INDEX,
+        "{\"mappings\":{\"properties\":{\"body\":{\"type\":\"text\"},"
+            + "\"idx\":{\"type\":\"integer\"}}}}");
+    Request bulk = new Request("POST", "/" + TEST_INDEX + "/_bulk?refresh=true");
+    bulk.setJsonEntity(
+        "{\"index\":{\"_id\":\"1\"}}\n"
+            + "{\"body\":\"ERROR something bad happened\",\"idx\":1}\n"
+            + "{\"index\":{\"_id\":\"2\"}}\n"
+            + "{\"body\":\"INFO all good\",\"idx\":2}\n");
+    performRequest(client(), bulk);
+  }
+
+  private String errorOf(String query) throws IOException {
+    ResponseException e =
+        assertThrows(ResponseException.class, () -> executeQuery(query));
+    return getResponseBody(e.getResponse());
+  }
+
+  private void assertFailsCleanly(String query, String expectedFunctionName)
+      throws IOException {
+    String message = errorOf(query);
+    assertFalse(
+        "Relevance function must not be pushed down as a script; it cannot compile on the shard."
+            + " Error was: "
+            + message,
+        message.contains("Failed to compile inline script"));
+    assertFalse(
+        "Query must fail on the coordinator, not as a shard failure. Error was: " + message,
+        message.contains("all shards failed"));
+    assertTrue(
+        String.format(
+            Locale.ROOT, "Error should name the function [%s]. Error was: %s", "match", message),
+        message.toLowerCase(Locale.ROOT).contains(expectedFunctionName));
+  }
+
+  /** A relevance function over a column computed by the query cannot be pushed down. */
+  @Test
+  public void relevanceOnEvalDerivedColumnFailsCleanly() throws IOException {
+    assertFailsCleanly(
+        String.format(
+            Locale.ROOT,
+            "source=%s | eval b2 = upper(body) | where match(b2, 'ERROR') | fields idx",
+            TEST_INDEX),
+        "match");
+  }
+
+  /** Same for a column produced by parse. */
+  @Test
+  public void relevanceOnParseDerivedColumnFailsCleanly() throws IOException {
+    assertFailsCleanly(
+        String.format(
+            Locale.ROOT,
+            "source=%s | parse body '(?<lvl>\\\\w+)' | where match(lvl, 'ERROR') | fields idx",
+            TEST_INDEX),
+        "match");
+  }
+
+  /** A relevance filter above an aggregation has no scan to be pushed onto. */
+  @Test
+  public void relevanceAboveAggregationFailsCleanly() throws IOException {
+    assertFailsCleanly(
+        String.format(Locale.ROOT, "source=%s | top 1 body | where match(body, 'ERROR')", TEST_INDEX),
+        "match");
+  }
+
+  /** A relevance function in a projection is never rewritten into a query. */
+  @Test
+  public void relevanceInProjectionFailsCleanly() throws IOException {
+    assertFailsCleanly(
+        String.format(
+            Locale.ROOT, "source=%s | eval m = match(body, 'ERROR') | fields idx, m", TEST_INDEX),
+        "match");
+  }
+
+  /**
+   * Regression guard: the pattern from the customer report -- a relevance filter combined with a
+   * LIKE filter on a pure text field -- must keep working. The LIKE goes down as a script while the
+   * relevance function goes down as a native match query.
+   */
+  @Test
+  public void relevanceCombinedWithLikeStillWorks() throws IOException {
+    JSONObject result =
+        executeQuery(
+            String.format(
+                Locale.ROOT,
+                "source=%s | where match(body, 'ERROR') | where like(body, '%%error%%') | fields"
+                    + " idx",
+                TEST_INDEX));
+    verifyDataRows(result, rows(1));
+  }
+
+  /** Regression guard: a plain relevance filter on an indexed field is unaffected. */
+  @Test
+  public void relevanceOnIndexedFieldStillWorks() throws IOException {
+    JSONObject result =
+        executeQuery(
+            String.format(
+                Locale.ROOT, "source=%s | where match(body, 'ERROR') | fields idx", TEST_INDEX));
+    verifyDataRows(result, rows(1));
+  }
+}

opensearch/src/main/java/org/opensearch/sql/opensearch/planner/rules/RelevanceFunctionPushdownRule.java

@@ -5,18 +5,13 @@
 
 package org.opensearch.sql.opensearch.planner.rules;
 
-import static org.opensearch.sql.calcite.utils.UserDefinedFunctionUtils.MULTI_FIELDS_RELEVANCE_FUNCTION_SET;
-import static org.opensearch.sql.calcite.utils.UserDefinedFunctionUtils.SINGLE_FIELD_RELEVANCE_FUNCTION_SET;
+import static org.opensearch.sql.calcite.utils.UserDefinedFunctionUtils.containsRelevanceFunction;
 
 import org.apache.calcite.plan.RelOptRuleCall;
 import org.apache.calcite.rel.AbstractRelNode;
 import org.apache.calcite.rel.core.Filter;
 import org.apache.calcite.rel.logical.LogicalFilter;
 import org.apache.calcite.rel.rules.SubstitutionRule;
-import org.apache.calcite.rex.RexCall;
-import org.apache.calcite.rex.RexNode;
-import org.apache.calcite.rex.RexVisitorImpl;
-import org.apache.calcite.sql.SqlOperator;
 import org.immutables.value.Value;
 import org.opensearch.sql.calcite.plan.rule.OpenSearchRuleConfig;
 import org.opensearch.sql.calcite.utils.PlanUtils;
@@ -61,47 +56,6 @@ protected void apply(RelOptRuleCall call, Filter filter, CalciteLogicalIndexScan
     }
   }
 
-  /**
-   * Checks if a RexNode contains any relevance functions.
-   *
-   * @param node The RexNode to check
-   * @return true if the node contains relevance functions, false otherwise
-   */
-  private boolean containsRelevanceFunction(RexNode node) {
-    RelevanceFunctionVisitor visitor = new RelevanceFunctionVisitor();
-    node.accept(visitor);
-    return visitor.hasRelevanceFunction();
-  }
-
-  /** Visitor to detect relevance functions in a RexNode tree. */
-  private static class RelevanceFunctionVisitor extends RexVisitorImpl<Void> {
-    private boolean foundRelevanceFunction = false;
-
-    RelevanceFunctionVisitor() {
-      super(true);
-    }
-
-    @Override
-    public Void visitCall(RexCall call) {
-      SqlOperator operator = call.getOperator();
-      String operatorName = operator.getName().toLowerCase();
-
-      // Check if this is a relevance function
-      if (SINGLE_FIELD_RELEVANCE_FUNCTION_SET.contains(operatorName)
-          || MULTI_FIELDS_RELEVANCE_FUNCTION_SET.contains(operatorName)) {
-        foundRelevanceFunction = true;
-        return null; // Stop traversing once we find a relevance function
-      }
-
-      // Continue traversing the tree
-      return super.visitCall(call);
-    }
-
-    boolean hasRelevanceFunction() {
-      return foundRelevanceFunction;
-    }
-  }
-
   /** Rule configuration. */
   @Value.Immutable
   public interface Config extends OpenSearchRuleConfig {