feat(sql): add profile support to analytics path

Add a `profile` boolean field to SQLQueryRequest and thread it through
the SQL REST handler to the analytics router. Mirrors PPL's existing
profile pattern: parsed from the JSON body's `profile` key, gated by
the same rules (only honored for non-explain JDBC requests on the
analytics engine path).

Replaces the hardcoded `false` in SQLPlugin#createSqlAnalyticsRouter so
analytics-engine queries now honor the request's profile flag. The V2
SQL engine path is unchanged; profile is silently ignored when the
request does not route to the analytics engine.

Refs: opensearch-project#5317
Signed-off-by: Chen Dai <daichen@amazon.com>

Author: dai-chen

docs/user/interfaces/endpoint.rst

@@ -266,6 +266,46 @@ Result set::
       "status": 200
     }
 
+Profile (Experimental)
+======================
+
+Description
+-----------
+
+Profiling captures per-stage timings (in milliseconds) for SQL query
+execution. To enable profiling, set ``"profile": true`` in the request
+body alongside ``"query"``.
+
+.. note::
+   The ``profile`` parameter only takes effect when the query runs on
+   the Analytics Engine. In all other cases the flag is silently ignored.
+
+   Profile output is returned only for regular query execution (not
+   ``_explain``) and only with the default ``format=jdbc``.
+
+Example
+-------
+
+Request::
+
+    POST /_plugins/_sql
+    {
+      "query": "SELECT customer_id, SUM(amount) FROM orders GROUP BY customer_id",
+      "profile": true
+    }
+
+Response::
+
+    {
+      "schema": [...],
+      "datarows": [...],
+      "profile": {
+        "summary": { "total_time_ms": 42 },
+        "phases": { "analyze": 3, "optimize": 5, "execute": 30, "format": 4 },
+        "plan": { ... }
+      }
+    }
+
 Fetch Size (PPL) [Experimental]
 ================================
 

legacy/src/main/java/org/opensearch/sql/legacy/plugin/RestSqlAction.java

@@ -145,13 +145,21 @@ protected RestChannelConsumer prepareRequest(RestRequest request, NodeClient cli
 
       Format format = SqlRequestParam.getFormat(request.params());
 
+      // Compute profile flag mirroring PPL's gating logic
+      boolean profileRequested =
+          sqlRequest.getJsonContent() != null
+              && sqlRequest.getJsonContent().optBoolean("profile", false);
+      boolean enableProfile =
+          profileRequested && isProfileSupported(request.path(), format, sqlRequest.getSql());
+
       SQLQueryRequest newSqlRequest =
           new SQLQueryRequest(
               sqlRequest.getJsonContent(),
               sqlRequest.getSql(),
               request.path(),
               request.params(),
-              sqlRequest.cursor());
+              sqlRequest.cursor(),
+              enableProfile);
 
       // Route to analytics engine for non-Lucene (e.g., Parquet-backed) indices.
       // The router returns true and sends the response directly if it handled the request.
@@ -366,4 +374,18 @@ private static ColumnTypeProvider performAnalysis(String sql) {
       return new ColumnTypeProvider();
     }
   }
+
+  private static final String DEFAULT_RESPONSE_FORMAT = "jdbc";
+
+  private static boolean isProfileSupported(String path, Format format, String query) {
+    boolean explainPath = isExplainRequest(path);
+    boolean explainQuery = query != null && query.trim().toLowerCase().startsWith("explain");
+    boolean isJdbcFormat =
+        format != null && DEFAULT_RESPONSE_FORMAT.equalsIgnoreCase(format.getFormatName());
+    return !explainPath && !explainQuery && isJdbcFormat;
+  }
+
+  private static boolean isExplainRequest(String path) {
+    return path != null && path.endsWith("/_explain");
+  }
 }

plugin/src/main/java/org/opensearch/sql/plugin/SQLPlugin.java

@@ -271,7 +271,7 @@ public void onFailure(Exception e) {
         unifiedQueryHandler.execute(
             sqlRequest.getQuery(),
             QueryType.SQL,
-            false,
+            sqlRequest.profile(),
             new ActionListener<>() {
               @Override
               public void onResponse(TransportPPLQueryResponse response) {

sql/src/main/java/org/opensearch/sql/sql/domain/SQLQueryRequest.java

@@ -15,6 +15,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
+import lombok.Setter;
 import lombok.ToString;
 import lombok.experimental.Accessors;
 import org.json.JSONObject;
@@ -27,7 +28,7 @@
 public class SQLQueryRequest {
   private static final String QUERY_FIELD_CURSOR = "cursor";
   private static final Set<String> SUPPORTED_FIELDS =
-      Set.of("query", "fetch_size", "parameters", QUERY_FIELD_CURSOR);
+      Set.of("query", "fetch_size", "parameters", QUERY_FIELD_CURSOR, "profile");
   private static final String QUERY_PARAMS_FORMAT = "format";
   private static final String QUERY_PARAMS_SANITIZE = "sanitize";
   private static final String QUERY_PARAMS_PRETTY = "pretty";
@@ -55,6 +56,11 @@ public class SQLQueryRequest {
   @Accessors(fluent = true)
   private boolean pretty = false;
 
+  @Setter
+  @Getter
+  @Accessors(fluent = true)
+  private boolean profile = false;
+
   private String cursor;
 
   /** Constructor of SQLQueryRequest that passes request params. */
@@ -64,6 +70,17 @@ public SQLQueryRequest(
       String path,
       Map<String, String> params,
       String cursor) {
+    this(jsonContent, query, path, params, cursor, false);
+  }
+
+  /** Constructor of SQLQueryRequest that passes request params and profile flag. */
+  public SQLQueryRequest(
+      JSONObject jsonContent,
+      String query,
+      String path,
+      Map<String, String> params,
+      String cursor,
+      boolean profile) {
     this.jsonContent = jsonContent;
     this.query = query;
     this.path = path;
@@ -72,6 +89,7 @@ public SQLQueryRequest(
     this.sanitize = shouldSanitize(params);
     this.pretty = shouldPretty(params);
     this.cursor = cursor;
+    this.profile = profile;
   }
 
   /**

sql/src/test/java/org/opensearch/sql/sql/domain/SQLQueryRequestTest.java

@@ -284,6 +284,43 @@ public void should_support_raw_format() {
     assertTrue(csvRequest.isSupported());
   }
 
+  @Test
+  public void should_support_query_with_profile_field() {
+    SQLQueryRequest request =
+        SQLQueryRequestBuilder.request("SELECT 1")
+            .jsonContent("{\"query\": \"SELECT 1\", \"profile\": true}")
+            .build();
+    assertTrue(request.isSupported());
+  }
+
+  @Test
+  public void should_have_profile_false_by_default() {
+    SQLQueryRequest request = SQLQueryRequestBuilder.request("SELECT 1").build();
+    assertFalse(request.profile());
+  }
+
+  @Test
+  public void should_set_profile_via_constructor() {
+    SQLQueryRequest request =
+        new SQLQueryRequest(
+            new JSONObject("{\"query\": \"SELECT 1\", \"profile\": true}"),
+            "SELECT 1",
+            "_plugins/_sql",
+            Map.of(),
+            null,
+            true);
+    assertTrue(request.profile());
+  }
+
+  @Test
+  public void should_support_query_and_profile_fields_only() {
+    SQLQueryRequest request =
+        SQLQueryRequestBuilder.request("SELECT 1")
+            .jsonContent("{\"query\": \"SELECT 1\", \"profile\": true}")
+            .build();
+    assertTrue(request.isSupported());
+  }
+
   /** SQL query request build helper to improve test data setup readability. */
   private static class SQLQueryRequestBuilder {
     private String jsonContent;