From 226e8499d7a898e2f9e9de26e322916901aa98fc Mon Sep 17 00:00:00 2001
From: Radhakrishnan Pachyappan <gingeekrishna@gmail.com>
Date: Sun, 5 Jul 2026 11:44:10 +0530
Subject: [PATCH] Fix SQL explain API rejecting format=json parameter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

isSupportedExplainFormat() only accepted "simple", "standard",
"extended", and "cost" — excluding "json". Before OpenSearch 3.0,
?format=json was valid for the explain endpoint, so existing workflows
that pass this parameter now receive:
  "Failed to create executor due to unknown response format: json"

The explain endpoint already returns JSON unconditionally regardless of
the format parameter, so accepting "json" is a pure backward-
compatibility restoration with no behavioral change.

Fixes #4373

Signed-off-by: Radhakrishnan Pachyappan <gingeekrishna@gmail.com>
---
 .../sql/sql/domain/SQLQueryRequest.java          |  6 +++++-
 .../sql/sql/domain/SQLQueryRequestTest.java      | 16 ++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/sql/src/main/java/org/opensearch/sql/sql/domain/SQLQueryRequest.java b/sql/src/main/java/org/opensearch/sql/sql/domain/SQLQueryRequest.java
index 456ea212717..a9d70126873 100644
--- a/sql/src/main/java/org/opensearch/sql/sql/domain/SQLQueryRequest.java
+++ b/sql/src/main/java/org/opensearch/sql/sql/domain/SQLQueryRequest.java
@@ -159,7 +159,11 @@ private boolean isSupportedFormat() {
   }
 
   private boolean isSupportedExplainFormat() {
-    return Stream.of("simple", "standard", "extended", "cost").anyMatch(format::equalsIgnoreCase);
+    // "json" is accepted for backward compatibility: the explain endpoint always returns JSON
+    // regardless of this parameter, so treating it as valid avoids the 400 regression
+    // introduced in OpenSearch 3.0. See https://github.com/opensearch-project/sql/issues/4373
+    return Stream.of("simple", "standard", "extended", "cost", "json")
+        .anyMatch(format::equalsIgnoreCase);
   }
 
   private String getFormat(Map<String, String> params) {
diff --git a/sql/src/test/java/org/opensearch/sql/sql/domain/SQLQueryRequestTest.java b/sql/src/test/java/org/opensearch/sql/sql/domain/SQLQueryRequestTest.java
index e5f2400e6cb..5c8b12256dd 100644
--- a/sql/src/test/java/org/opensearch/sql/sql/domain/SQLQueryRequestTest.java
+++ b/sql/src/test/java/org/opensearch/sql/sql/domain/SQLQueryRequestTest.java
@@ -104,6 +104,22 @@ public void should_support_explain_format() {
         () -> assertTrue(explainRequest.isSupported()));
   }
 
+  @Test
+  public void should_support_explain_with_json_format() {
+    // Regression test for https://github.com/opensearch-project/sql/issues/4373.
+    // ?format=json was accepted before OpenSearch 3.0 and should continue to be valid.
+    // The explain endpoint always returns JSON regardless of this parameter.
+    SQLQueryRequest explainRequest =
+        SQLQueryRequestBuilder.request("SELECT 1")
+            .path("_plugins/_sql/_explain")
+            .params(Map.of("format", "json"))
+            .build();
+
+    assertAll(
+        () -> assertTrue(explainRequest.isExplainRequest()),
+        () -> assertTrue(explainRequest.isSupported()));
+  }
+
   @Test
   public void should_not_support_explain_with_unsupported_explain_format() {
     SQLQueryRequest explainRequest =