Add 'reason' key that defaults to the exception message

Signed-off-by: Simeon Widdis <sawiddis@amazon.com>

Author: Swiddis

core/src/main/java/org/opensearch/sql/calcite/utils/CalciteToolsHelper.java

@@ -30,7 +30,6 @@
 import static java.util.Objects.requireNonNull;
 import static org.opensearch.sql.monitor.profile.MetricName.OPTIMIZE;
 
-import com.google.common.base.Throwables;
 import com.google.common.collect.ImmutableList;
 import java.lang.reflect.Type;
 import java.sql.Connection;
@@ -480,8 +479,6 @@ public RelNode visit(TableScan scan) {
         optimizeTime.set(System.nanoTime() - startTime);
         return preparedStatement;
       } catch (SQLException e) {
-        Throwables.throwIfUnchecked(e);
-
         // Detect if error is due to window functions in unsupported context (bins on time fields)
         ErrorReport.Builder report =
             ErrorReport.wrap(e)

docs/user/ppl/cmd/mvcombine.md

@@ -124,6 +124,6 @@ source=mvcombine_data
 
 Expected output:
 ```text
-{'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query'}, 'details': 'Field [does_not_exist] not found.', 'location': ['while preparing and validating the query plan'], 'code': 'FIELD_NOT_FOUND', 'type': 'IllegalArgumentException'}
+{'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query'}, 'reason': 'Field [does_not_exist] not found.', 'details': 'Field [does_not_exist] not found.', 'location': ['while preparing and validating the query plan'], 'code': 'FIELD_NOT_FOUND', 'type': 'IllegalArgumentException'}
 Error: Query returned no data
 ```

docs/user/ppl/cmd/mvexpand.md

@@ -132,6 +132,6 @@ source=people
 
 Expected output:
 ```text
-{'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query', 'command': 'mvexpand'}, 'details': "Field 'tags' not found in the schema", 'location': ['while preparing and validating the query plan', 'while evaluating the input field for mvexpand'], 'code': 'FIELD_NOT_FOUND', 'type': 'SemanticCheckException'}
+{'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query', 'command': 'mvexpand'}, 'reason': "Field 'tags' not found in the schema", 'details': "Field 'tags' not found in the schema", 'location': ['while preparing and validating the query plan', 'while evaluating the input field for mvexpand'], 'code': 'FIELD_NOT_FOUND', 'type': 'SemanticCheckException'}
 Error: Query returned no data
 ```

docs/user/ppl/cmd/rex.md

@@ -228,7 +228,7 @@ source=accounts
 The query returns the following results:
 
 ```text
-{'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query', 'command': 'rex'}, 'details': "Invalid capture group name 'user_name'.", 'location': ['while preparing and validating the query plan', 'while processing the rex command', 'while validating the capture groups for the pattern'], 'code': 'SYNTAX_ERROR', 'type': 'IllegalArgumentException', 'suggestion': 'Java Regex capture groups must be alphanumeric and start with a letter. Update the capture group to be alphanumeric.'}
+{'reason': "Invalid capture group name 'user_name'.", 'code': 'SYNTAX_ERROR', 'suggestion': 'Java Regex capture groups must be alphanumeric and start with a letter. Update the capture group to be alphanumeric.', 'context': {'stage': 'analyzing', 'stage_description': 'Parsing and validating the query', 'command': 'rex'}, 'details': "Invalid capture group name 'user_name'.", 'location': ['while preparing and validating the query plan', 'while processing the rex command', 'while validating the capture groups for the pattern'], 'type': 'IllegalArgumentException'}
 Error: Query returned no data
 ```
 

docs/user/ppl/interfaces/protocol.md

@@ -125,6 +125,7 @@ Expected output:
       "index_name": "unknown",
       "stage_description": "Parsing and validating the query"
     },
+    "reason": "no such index [unknown]",
     "details": "no such index [unknown]",
     "location": [
       "while preparing and validating the query plan",

opensearch/src/main/java/org/opensearch/sql/opensearch/response/error/ErrorMessage.java

@@ -63,8 +63,20 @@ public String toString() {
   }
 
   private JSONObject getErrorAsJson() {
-    if (exception instanceof ErrorReport) {
-      return new JSONObject(((ErrorReport) exception).toJsonMap());
+    if (exception instanceof ErrorReport errorReport) {
+      JSONObject errorJson = new JSONObject(errorReport.toJsonMap());
+      // Add 'reason' field for backward compatibility with existing clients
+      // Use the underlying exception message as 'reason' (broad error description)
+      // while 'details' contains the more precise handwritten message
+      if (!errorJson.has("reason")) {
+        Exception cause = errorReport.getCause();
+        String reasonMessage =
+            cause.getLocalizedMessage() != null ? cause.getLocalizedMessage() : cause.getMessage();
+        if (reasonMessage != null) {
+          errorJson.put("reason", reasonMessage);
+        }
+      }
+      return errorJson;
     }
 
     JSONObject errorJson = new JSONObject();