Add UnifiedQueryParser with language-specific implementations

Extract parsing logic from UnifiedQueryPlanner into a UnifiedQueryParser
interface with language-specific implementations: PPLQueryParser (returns
UnresolvedPlan) and CalciteSqlQueryParser (returns SqlNode).

UnifiedQueryContext owns the parser instance, created eagerly by the
builder which has direct access to query type and future SQL config.
Each implementation receives only its required dependencies:
PPLQueryParser takes Settings, CalciteSqlQueryParser takes
FrameworkConfig. UnifiedQueryPlanner.CustomVisitorStrategy now obtains
the parser from the context via the interface type.

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

Author: dai-chen

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

@@ -13,7 +13,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
-import lombok.Value;
+import lombok.Getter;
 import org.apache.calcite.avatica.util.Casing;
 import org.apache.calcite.jdbc.CalciteSchema;
 import org.apache.calcite.plan.RelTraitDef;
@@ -24,6 +24,9 @@
 import org.apache.calcite.tools.FrameworkConfig;
 import org.apache.calcite.tools.Frameworks;
 import org.apache.calcite.tools.Programs;
+import org.opensearch.sql.api.parser.CalciteSqlQueryParser;
+import org.opensearch.sql.api.parser.PPLQueryParser;
+import org.opensearch.sql.api.parser.UnifiedQueryParser;
 import org.opensearch.sql.calcite.CalcitePlanContext;
 import org.opensearch.sql.calcite.SysLimit;
 import org.opensearch.sql.common.setting.Settings;
@@ -34,14 +37,24 @@
  * centralizes configuration for catalog schemas, query type, execution limits, and other settings,
  * enabling consistent behavior across all unified query operations.
  */
-@Value
+@Getter
 public class UnifiedQueryContext implements AutoCloseable {
 
   /** CalcitePlanContext containing Calcite framework configuration and query type. */
-  CalcitePlanContext planContext;
+  private final CalcitePlanContext planContext;
 
   /** Settings containing execution limits and feature flags used by parsers and planners. */
-  Settings settings;
+  private final Settings settings;
+
+  /** Query parser created eagerly from this context's configuration. */
+  private final UnifiedQueryParser<?> parser;
+
+  private UnifiedQueryContext(
+      CalcitePlanContext planContext, Settings settings, UnifiedQueryParser<?> parser) {
+    this.planContext = planContext;
+    this.settings = settings;
+    this.parser = parser;
+  }
 
   /**
    * Closes the underlying resource managed by this context.
@@ -152,7 +165,14 @@ public UnifiedQueryContext build() {
       CalcitePlanContext planContext =
           CalcitePlanContext.create(
               buildFrameworkConfig(), SysLimit.fromSettings(settings), queryType);
-      return new UnifiedQueryContext(planContext, settings);
+      return new UnifiedQueryContext(planContext, settings, createParser(planContext, settings));
+    }
+
+    private UnifiedQueryParser<?> createParser(CalcitePlanContext planContext, Settings settings) {
+      return switch (queryType) {
+        case PPL -> new PPLQueryParser(settings);
+        case SQL -> new CalciteSqlQueryParser(planContext);
+      };
     }
 
     private Settings buildSettings() {

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

@@ -6,7 +6,6 @@
 package org.opensearch.sql.api;
 
 import lombok.RequiredArgsConstructor;
-import org.antlr.v4.runtime.tree.ParseTree;
 import org.apache.calcite.rel.RelCollation;
 import org.apache.calcite.rel.RelCollations;
 import org.apache.calcite.rel.RelNode;
@@ -16,15 +15,11 @@
 import org.apache.calcite.sql.SqlNode;
 import org.apache.calcite.tools.Frameworks;
 import org.apache.calcite.tools.Planner;
-import org.opensearch.sql.ast.statement.Query;
-import org.opensearch.sql.ast.statement.Statement;
+import org.opensearch.sql.api.parser.UnifiedQueryParser;
 import org.opensearch.sql.ast.tree.UnresolvedPlan;
 import org.opensearch.sql.calcite.CalciteRelNodeVisitor;
 import org.opensearch.sql.common.antlr.SyntaxCheckException;
 import org.opensearch.sql.executor.QueryType;
-import org.opensearch.sql.ppl.antlr.PPLSyntaxParser;
-import org.opensearch.sql.ppl.parser.AstBuilder;
-import org.opensearch.sql.ppl.parser.AstStatementBuilder;
 
 /**
  * {@code UnifiedQueryPlanner} provides a high-level API for parsing and analyzing queries using the
@@ -87,36 +82,26 @@ public RelNode plan(String query) throws Exception {
     }
   }
 
-  /** AST-based planning via ANTLR parser → UnresolvedPlan → CalciteRelNodeVisitor. */
-  @RequiredArgsConstructor
+  /** AST-based planning via context-owned parser → UnresolvedPlan → CalciteRelNodeVisitor. */
   private static class CustomVisitorStrategy implements PlanningStrategy {
     private final UnifiedQueryContext context;
-    private final PPLSyntaxParser parser = new PPLSyntaxParser();
+    private final UnifiedQueryParser<UnresolvedPlan> parser;
     private final CalciteRelNodeVisitor relNodeVisitor =
         new CalciteRelNodeVisitor(new EmptyDataSourceService());
 
+    @SuppressWarnings("unchecked")
+    CustomVisitorStrategy(UnifiedQueryContext context) {
+      this.context = context;
+      this.parser = (UnifiedQueryParser<UnresolvedPlan>) context.getParser();
+    }
+
     @Override
     public RelNode plan(String query) {
-      UnresolvedPlan ast = parse(query);
+      UnresolvedPlan ast = parser.parse(query);
       RelNode logical = relNodeVisitor.analyze(ast, context.getPlanContext());
       return preserveCollation(logical);
     }
 
-    private UnresolvedPlan parse(String query) {
-      ParseTree cst = parser.parse(query);
-      AstStatementBuilder astStmtBuilder =
-          new AstStatementBuilder(
-              new AstBuilder(query, context.getSettings()),
-              AstStatementBuilder.StatementBuilderContext.builder().build());
-      Statement statement = cst.accept(astStmtBuilder);
-
-      if (statement instanceof Query) {
-        return ((Query) statement).getPlan();
-      }
-      throw new UnsupportedOperationException(
-          "Only query statements are supported but got " + statement.getClass().getSimpleName());
-    }
-
     private RelNode preserveCollation(RelNode logical) {
       RelCollation collation = logical.getTraitSet().getCollation();
       if (!(logical instanceof Sort) && collation != RelCollations.EMPTY) {

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.api.parser;
+
+import lombok.RequiredArgsConstructor;
+import org.apache.calcite.sql.SqlNode;
+import org.apache.calcite.sql.parser.SqlParseException;
+import org.apache.calcite.sql.parser.SqlParser;
+import org.opensearch.sql.calcite.CalcitePlanContext;
+import org.opensearch.sql.common.antlr.SyntaxCheckException;
+
+/** Calcite SQL query parser that produces {@link SqlNode} as the native parse result. */
+@RequiredArgsConstructor
+public class CalciteSqlQueryParser implements UnifiedQueryParser<SqlNode> {
+
+  /** Calcite plan context providing parser configuration (e.g., case sensitivity, conformance). */
+  private final CalcitePlanContext planContext;
+
+  @Override
+  public SqlNode parse(String query) {
+    try {
+      return SqlParser.create(query, planContext.config.getParserConfig()).parseQuery();
+    } catch (SqlParseException e) {
+      throw new SyntaxCheckException("Failed to parse SQL query: " + e.getMessage());
+    }
+  }
+}

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.api.parser;
+
+import lombok.RequiredArgsConstructor;
+import org.antlr.v4.runtime.tree.ParseTree;
+import org.opensearch.sql.ast.statement.Query;
+import org.opensearch.sql.ast.statement.Statement;
+import org.opensearch.sql.ast.tree.UnresolvedPlan;
+import org.opensearch.sql.common.setting.Settings;
+import org.opensearch.sql.ppl.antlr.PPLSyntaxParser;
+import org.opensearch.sql.ppl.parser.AstBuilder;
+import org.opensearch.sql.ppl.parser.AstStatementBuilder;
+
+/** PPL query parser that produces {@link UnresolvedPlan} as the native parse result. */
+@RequiredArgsConstructor
+public class PPLQueryParser implements UnifiedQueryParser<UnresolvedPlan> {
+
+  /** Settings containing execution limits and feature flags used by AST builders. */
+  private final Settings settings;
+
+  /** Reusable ANTLR-based PPL syntax parser. Stateless and thread-safe. */
+  private final PPLSyntaxParser syntaxParser = new PPLSyntaxParser();
+
+  @Override
+  public UnresolvedPlan parse(String query) {
+    ParseTree cst = syntaxParser.parse(query);
+    AstStatementBuilder astStmtBuilder =
+        new AstStatementBuilder(
+            new AstBuilder(query, settings),
+            AstStatementBuilder.StatementBuilderContext.builder().build());
+    Statement statement = cst.accept(astStmtBuilder);
+
+    if (statement instanceof Query) {
+      return ((Query) statement).getPlan();
+    }
+    throw new UnsupportedOperationException(
+        "Only query statements are supported but got " + statement.getClass().getSimpleName());
+  }
+}

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

@@ -0,0 +1,23 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.api.parser;
+
+/**
+ * Language-neutral query parser interface. Returns the native parse result for the language (e.g.,
+ * {@code UnresolvedPlan} for PPL, {@code SqlNode} for Calcite SQL).
+ *
+ * @param <R> the native parse result type for this language
+ */
+public interface UnifiedQueryParser<R> {
+
+  /**
+   * Parses the query and returns the native parse result.
+   *
+   * @param query the raw query string
+   * @return the native parse result
+   */
+  R parse(String query);
+}

api/src/test/java/org/opensearch/sql/api/parser/UnifiedQueryParserTest.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.api.parser;
+
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertThrows;
+
+import org.apache.calcite.sql.SqlNode;
+import org.junit.Test;
+import org.opensearch.sql.api.UnifiedQueryTestBase;
+import org.opensearch.sql.ast.tree.UnresolvedPlan;
+import org.opensearch.sql.common.antlr.SyntaxCheckException;
+import org.opensearch.sql.executor.QueryType;
+
+public class UnifiedQueryParserTest extends UnifiedQueryTestBase {
+
+  @Test
+  public void testPplParseReturnsUnresolvedPlan() {
+    UnresolvedPlan ast = (UnresolvedPlan) context.getParser().parse("source = catalog.employees");
+    assertNotNull(ast);
+  }
+
+  @Test
+  public void testPplParseSyntaxErrorThrows() {
+    assertThrows(SyntaxCheckException.class, () -> context.getParser().parse("not a valid query"));
+  }
+
+  @Test
+  public void testSqlParseReturnsSqlNode() throws Exception {
+    try (var sqlContext = buildContext(QueryType.SQL)) {
+      SqlNode node = (SqlNode) sqlContext.getParser().parse("SELECT * FROM my_index");
+      assertNotNull(node);
+    }
+  }
+
+  @Test
+  public void testSqlParseSyntaxErrorThrows() throws Exception {
+    try (var sqlContext = buildContext(QueryType.SQL)) {
+      assertThrows(
+          SyntaxCheckException.class, () -> sqlContext.getParser().parse("NOT VALID SQL !!!"));
+    }
+  }
+}