Add Calcite native SQL planning in UnifiedQueryPlanner (opensearch-project#5257)

* feat(api): Add Calcite native SQL planning path in UnifiedQueryPlanner

Add SQL support to the unified query API using Calcite's native parser
pipeline (SqlParser → SqlValidator → SqlToRelConverter → RelNode),
bypassing the ANTLR parser used by PPL.

Changes:
- UnifiedQueryPlanner: use PlanningStrategy to dispatch
  CalciteNativeStrategy vs CustomVisitorStrategy
- CalciteNativeStrategy: Calcite Planner with try-with-resources
  for ANSI SQL
- CustomVisitorStrategy: ANTLR-based path for PPL (and future SQL V2)
- UnifiedQueryContext: SqlParser.Config with Casing.UNCHANGED to
  preserve lowercase OpenSearch index names

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

* test(api): Add SQL planner tests and refactor test base for multi-language support

- Refactor UnifiedQueryTestBase with queryType() hook for subclass override
- Add UnifiedSqlQueryPlannerTest covering SELECT, WHERE, GROUP BY, JOIN,
  ORDER BY, subquery, case sensitivity, namespaces, and error handling
- Update UnifiedQueryContextTest to verify SQL context creation

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

* perf(benchmarks): Add SQL queries to UnifiedQueryBenchmark

Add language (PPL/SQL) and queryPattern param dimensions for
side-by-side comparison of equivalent queries across both languages.
Remove separate UnifiedSqlQueryBenchmark in favor of unified class.

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

* docs(api): Update README to reflect SQL support in UnifiedQueryPlanner

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

* fix(api): Normalize trailing whitespace in assertPlan comparison

RelOptUtil.toString() appends a trailing newline after the last plan
node, which doesn't match Java text block expectations. Also add
\r\n normalization for Windows CI compatibility, consistent with
the existing pattern in core module tests.

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

---------

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

Author: dai-chen

api/README.md

@@ -8,8 +8,7 @@ This module provides components organized into two main areas aligned with the [
 
 ### Unified Language Specification
 
-- **`UnifiedQueryParser`**: Parses PPL (Piped Processing Language) or SQL queries and returns the native parse result (`UnresolvedPlan` for PPL, `SqlNode` for Calcite SQL).
-- **`UnifiedQueryPlanner`**: Accepts PPL or SQL queries and returns Calcite `RelNode` logical plans as intermediate representation.
+- **`UnifiedQueryPlanner`**: Accepts PPL (Piped Processing Language) or SQL queries and returns Calcite `RelNode` logical plans as intermediate representation.
 - **`UnifiedQueryTranspiler`**: Converts Calcite logical plans (`RelNode`) into SQL strings for various target databases using different SQL dialects.
 
 ### Unified Execution Runtime
@@ -43,20 +42,6 @@ UnifiedQueryContext context = UnifiedQueryContext.builder()
     .build();
 ```
 
-### UnifiedQueryParser
-
-Use `UnifiedQueryParser` to parse queries into their native parse tree. The parser is owned by `UnifiedQueryContext` and returns the native parse result for each language.
-
-```java
-// PPL parsing
-UnresolvedPlan ast = (UnresolvedPlan) context.getParser().parse("source = logs | where status = 200");
-
-// SQL parsing (with QueryType.SQL context)
-SqlNode sqlNode = (SqlNode) sqlContext.getParser().parse("SELECT * FROM logs WHERE status = 200");
-```
-
-Callers can then use each language's native visitor infrastructure (`AbstractNodeVisitor` for PPL, `SqlBasicVisitor` for Calcite SQL) on the typed result for further analysis.
-
 ### UnifiedQueryPlanner
 
 Use `UnifiedQueryPlanner` to parse and analyze PPL or SQL queries into Calcite logical plans. The planner accepts a `UnifiedQueryContext` and can be reused for multiple queries.
@@ -194,59 +179,6 @@ try (UnifiedQueryContext context = UnifiedQueryContext.builder()
 }
 ```
 
-## Profiling
-
-The unified query API supports the same [profiling capability](../docs/user/ppl/interfaces/endpoint.md#profile-experimental) as the PPL REST endpoint. When enabled, each unified query component automatically collects per-phase timing metrics. For code outside unified query components (e.g., `PreparedStatement.executeQuery()` or response formatting), `context.measure()` records custom phases into the same profile.
-
-```java
-try (UnifiedQueryContext context = UnifiedQueryContext.builder()
-    .language(QueryType.PPL)
-    .catalog("catalog", schema)
-    .defaultNamespace("catalog")
-    .profiling(true)
-    .build()) {
-
-  // Auto-profiled: ANALYZE
-  RelNode plan = new UnifiedQueryPlanner(context).plan(query);
-
-  // Auto-profiled: OPTIMIZE
-  PreparedStatement stmt = new UnifiedQueryCompiler(context).compile(plan);
-
-  // User-profiled via measure()
-  ResultSet rs = context.measure(MetricName.EXECUTE, stmt::executeQuery);
-  String json = context.measure(MetricName.FORMAT, () -> formatter.format(result));
-
-  // Retrieve profile snapshot
-  QueryProfile profile = context.getProfile();
-}
-```
-
-The returned `QueryProfile` follows the same JSON structure as the REST API:
-
-```json
-{
-  "summary": {
-    "total_time_ms": 33.34
-  },
-  "phases": {
-    "analyze": { "time_ms": 8.68 },
-    "optimize": { "time_ms": 18.2 },
-    "execute": { "time_ms": 4.87 },
-    "format": { "time_ms": 0.05 }
-  },
-  "plan": {
-    "node": "EnumerableCalc",
-    "time_ms": 4.82,
-    "rows": 2,
-    "children": [
-      { "node": "CalciteEnumerableIndexScan", "time_ms": 4.12, "rows": 2 }
-    ]
-  }
-}
-```
-
-When profiling is disabled (the default), all components execute with zero overhead.
-
 ## Development & Testing
 
 A set of unit tests is provided to validate planner behavior.

api/src/testFixtures/java/org/opensearch/sql/api/UnifiedQueryTestBase.java

@@ -59,7 +59,7 @@ protected Map<String, Table> getTableMap() {
           }
         };
 
-    context = contextBuilder().build();
+    context = buildContext(queryType());
     planner = new UnifiedQueryPlanner(context);
   }
 
@@ -70,12 +70,12 @@ protected QueryType queryType() {
     return QueryType.PPL;
   }
 
-  /**
-   * Creates a pre-configured context builder with test schema. Subclasses can override to customize
-   * context configuration (e.g., enable profiling).
-   */
-  protected UnifiedQueryContext.Builder contextBuilder() {
-    return UnifiedQueryContext.builder().language(queryType()).catalog(DEFAULT_CATALOG, testSchema);
+  /** Builds a UnifiedQueryContext with the test schema for the given query type. */
+  protected UnifiedQueryContext buildContext(QueryType queryType) {
+    return UnifiedQueryContext.builder()
+        .language(queryType)
+        .catalog(DEFAULT_CATALOG, testSchema)
+        .build();
   }
 
   @After