feat: V2 named-argument syntax with NamedArgRewriter

Add NamedArgRewriter SqlShuttle that normalizes V2/PPL relevance syntax
into MAP-based form before Calcite validation. Transforms positional and
key=value arguments into MAP[paramName, value] pairs matching PPL's
internal representation for uniform pushdown rules.

Refactor UnifiedFunctionSpec to instance-based design with fluent builder
and Category record for grouping. Use SqlUserDefinedFunction for
consistency with PPL path. Add error tests and QueryErrorAssert to test
base.

Signed-off-by: Chen Dai <daichen@amazon.com>

Author: dai-chen

api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java

@@ -25,6 +25,7 @@
 import org.apache.calcite.schema.SchemaPlus;
 import org.apache.calcite.sql.fun.SqlStdOperatorTable;
 import org.apache.calcite.sql.parser.SqlParser;
+import org.apache.calcite.sql.util.SqlOperatorTables;
 import org.apache.calcite.tools.FrameworkConfig;
 import org.apache.calcite.tools.Frameworks;
 import org.apache.calcite.tools.Programs;
@@ -241,12 +242,13 @@ public List<?> getSettings() {
     private FrameworkConfig buildFrameworkConfig() {
       SchemaPlus rootSchema = CalciteSchema.createRootSchema(true, cacheMetadata).plus();
       catalogs.forEach(rootSchema::add);
-      UnifiedFunctionSpec.registerAll(rootSchema);
 
       SchemaPlus defaultSchema = findSchemaByPath(rootSchema, defaultNamespace);
       return Frameworks.newConfigBuilder()
           .parserConfig(buildParserConfig())
-          .operatorTable(SqlStdOperatorTable.instance())
+          .operatorTable(
+              SqlOperatorTables.chain(
+                  SqlStdOperatorTable.instance(), UnifiedFunctionSpec.RELEVANCE.operatorTable()))
           .defaultSchema(defaultSchema)
           .traitDefs((List<RelTraitDef>) null)
           .programs(Programs.calc(DefaultRelMetadataProvider.INSTANCE))

api/src/main/java/org/opensearch/sql/api/UnifiedQueryPlanner.java

@@ -7,6 +7,7 @@
 
 import static org.opensearch.sql.monitor.profile.MetricName.ANALYZE;
 
+import java.util.function.UnaryOperator;
 import lombok.RequiredArgsConstructor;
 import org.apache.calcite.rel.RelCollation;
 import org.apache.calcite.rel.RelCollations;
@@ -17,6 +18,7 @@
 import org.apache.calcite.sql.SqlNode;
 import org.apache.calcite.tools.Frameworks;
 import org.apache.calcite.tools.Planner;
+import org.opensearch.sql.api.parser.NamedArgRewriter;
 import org.opensearch.sql.api.parser.UnifiedQueryParser;
 import org.opensearch.sql.ast.tree.UnresolvedPlan;
 import org.opensearch.sql.calcite.CalciteRelNodeVisitor;
@@ -36,6 +38,9 @@ public class UnifiedQueryPlanner {
   /** Unified query context for profiling support. */
   private final UnifiedQueryContext context;
 
+  /** Post-planning validators applied to the RelNode after planning. */
+  private final UnaryOperator<RelNode> postProcessor;
+
   /**
    * Constructs a UnifiedQueryPlanner with a unified query context.
    *
@@ -47,6 +52,7 @@ public UnifiedQueryPlanner(UnifiedQueryContext context) {
         context.getPlanContext().queryType == QueryType.SQL
             ? new CalciteNativeStrategy(context)
             : new CustomVisitorStrategy(context);
+    this.postProcessor = buildPostProcessor(context);
   }
 
   /**
@@ -58,7 +64,7 @@ public UnifiedQueryPlanner(UnifiedQueryContext context) {
    */
   public RelNode plan(String query) {
     try {
-      return context.measure(ANALYZE, () -> strategy.plan(query));
+      return context.measure(ANALYZE, () -> postProcessor.apply(strategy.plan(query)));
     } catch (SyntaxCheckException e) {
       // Re-throw syntax error without wrapping
       throw e;
@@ -67,6 +73,10 @@ public RelNode plan(String query) {
     }
   }
 
+  private static UnaryOperator<RelNode> buildPostProcessor(UnifiedQueryContext context) {
+    return UnaryOperator.identity();
+  }
+
   /** Strategy interface for language-specific planning logic. */
   private interface PlanningStrategy {
     RelNode plan(String query) throws Exception;
@@ -81,7 +91,8 @@ private static class CalciteNativeStrategy implements PlanningStrategy {
     public RelNode plan(String query) throws Exception {
       try (Planner planner = Frameworks.getPlanner(context.getPlanContext().config)) {
         SqlNode parsed = planner.parse(query);
-        SqlNode validated = planner.validate(parsed);
+        SqlNode rewritten = parsed.accept(NamedArgRewriter.INSTANCE);
+        SqlNode validated = planner.validate(rewritten);
         RelRoot relRoot = planner.rel(validated);
         return relRoot.project();
       }

api/src/main/java/org/opensearch/sql/api/parser/NamedArgRewriter.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.api.parser;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.apache.calcite.sql.SqlBasicCall;
+import org.apache.calcite.sql.SqlCall;
+import org.apache.calcite.sql.SqlKind;
+import org.apache.calcite.sql.SqlLiteral;
+import org.apache.calcite.sql.SqlNode;
+import org.apache.calcite.sql.fun.SqlStdOperatorTable;
+import org.apache.calcite.sql.parser.SqlParserPos;
+import org.apache.calcite.sql.util.SqlShuttle;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.opensearch.sql.api.spec.UnifiedFunctionSpec;
+
+/**
+ * Pre-validation rewriter that normalizes V2/PPL relevance function syntax into MAP-based form
+ * matching PPL's internal representation. This ensures both SQL and PPL paths produce identical
+ * query plans for pushdown rules.
+ *
+ * <p>Transforms: {@code match(name, 'John', operator='AND', boost=2.0)} into: {@code
+ * match(MAP['field', name], MAP['query', 'John'], MAP['operator', 'AND'], MAP['boost', 2.0])}
+ *
+ * <p>Param names are resolved via {@link UnifiedFunctionSpec#getParamNames} from the operator's
+ * {@link org.apache.calcite.sql.type.SqlOperandMetadata}. This runs before Calcite validation, when
+ * operators are still unresolved.
+ */
+public final class NamedArgRewriter extends SqlShuttle {
+
+  public static final NamedArgRewriter INSTANCE = new NamedArgRewriter();
+
+  private NamedArgRewriter() {}
+
+  @Override
+  public @Nullable SqlNode visit(SqlCall call) {
+    SqlCall visited = (SqlCall) super.visit(call);
+    if (visited == null) {
+      return null;
+    }
+    UnifiedFunctionSpec spec = UnifiedFunctionSpec.of(visited.getOperator().getName());
+    if (spec == null) {
+      return visited;
+    }
+    return rewriteToMaps(visited, spec.getParamNames());
+  }
+
+  /**
+   * Wraps positional args in MAP[paramName, value] and flattens {@code key=value} comparisons into
+   * MAP[key, value]. Produces the same MAP-based form as PPL's internal representation.
+   */
+  private static SqlNode rewriteToMaps(SqlCall call, List<String> paramNames) {
+    List<SqlNode> operands = call.getOperandList();
+    List<SqlNode> result = new ArrayList<>();
+
+    for (int i = 0; i < operands.size(); i++) {
+      SqlNode operand = operands.get(i);
+      if (operand != null && operand.getKind() == SqlKind.EQUALS) {
+        // Optional param: operator='AND' → MAP['operator', 'AND']
+        SqlCall eq = (SqlCall) operand;
+        result.add(toMap(eq.operand(0).toString(), eq.operand(1)));
+      } else if (i < paramNames.size()) {
+        // Required positional param: name → MAP['field', name]
+        result.add(toMap(paramNames.get(i), operand));
+      } else {
+        result.add(operand);
+      }
+    }
+    return new SqlBasicCall(
+        call.getOperator(), result.toArray(SqlNode[]::new), call.getParserPosition());
+  }
+
+  private static SqlNode toMap(String key, SqlNode value) {
+    return new SqlBasicCall(
+        SqlStdOperatorTable.MAP_VALUE_CONSTRUCTOR,
+        new SqlNode[] {SqlLiteral.createCharString(key, SqlParserPos.ZERO), value},
+        SqlParserPos.ZERO);
+  }
+}