Adopt ErrorReport for unresolvable alias path error

Wrap the SemanticCheckException in an ErrorReport (the report-builder
interface from opensearch-project#5266) so the error carries structured context as it bubbles
up: FIELD_NOT_FOUND code, ANALYZING stage, a location chain, the alias field
and path as context, and a fix suggestion. On the PPL/Calcite path this
renders as a rich structured error; on the SQL JDBC path it still returns a
clear 400 (RestSqlAction unwraps to the SemanticCheckException cause), though
the JdbcResponseFormatter does not yet render the ErrorReport structure.

Update the unit test to assert the ErrorReport code/stage/context/cause, the
SQL IT for the ErrorReport type, and add a PPL IT asserting the structured
FIELD_NOT_FOUND error in CalciteErrorReportStageIT.

Signed-off-by: Jialiang Liang <jiallian@amazon.com>

Author: RyanL1997

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteErrorReportStageIT.java

@@ -11,6 +11,7 @@
 import java.io.IOException;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
+import org.opensearch.client.Request;
 import org.opensearch.client.ResponseException;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
 
@@ -214,4 +215,36 @@ public void testStageDescriptionIsUserFriendly() throws IOException {
             || stageDescription.toLowerCase().contains("run")
             || stageDescription.toLowerCase().contains("query"));
   }
+
+  // An alias field whose path targets a text multi-field (e.g. "source.keyword") is not present in
+  // the flattened mapping. It used to surface an opaque NullPointerException; it must now report a
+  // structured FIELD_NOT_FOUND error with a suggestion.
+  @Test
+  public void testAliasToUnresolvablePathIncludesStructuredError() throws IOException {
+    String index = "test_alias_unresolved_keyword";
+    Request createIndex = new Request("PUT", "/" + index);
+    createIndex.setJsonEntity(
+        "{ \"mappings\": { \"properties\": {"
+            + "  \"source\": { \"type\": \"text\", \"fields\": { \"keyword\": { \"type\":"
+            + " \"keyword\" } } },"
+            + "  \"source_alias\": { \"type\": \"alias\", \"path\": \"source.keyword\" } } } }");
+    client().performRequest(createIndex);
+
+    ResponseException exception =
+        assertThrows(ResponseException.class, () -> executeQuery("source=" + index));
+
+    JSONObject error =
+        new JSONObject(getResponseBody(exception.getResponse())).getJSONObject("error");
+
+    assertEquals("FIELD_NOT_FOUND", error.getString("code"));
+    assertTrue(
+        "Details should name the alias field and path",
+        error
+            .getString("details")
+            .contains("Alias field [source_alias] refers to unresolved path [source.keyword]"));
+    JSONObject context = error.getJSONObject("context");
+    assertEquals("source_alias", context.getString("alias_field"));
+    assertEquals("source.keyword", context.getString("alias_path"));
+    assertTrue("Should include a suggestion", error.has("suggestion"));
+  }
 }

integ-test/src/test/java/org/opensearch/sql/sql/QueryValidationIT.java

@@ -117,7 +117,7 @@ public void testAliasToKeywordMultiFieldFailsWithBadRequest() throws IOException
 
     expectResponseException()
         .hasStatusCode(BAD_REQUEST)
-        .hasErrorType("SemanticCheckException")
+        .hasErrorType("ErrorReport")
         .containsMessage("Alias field [source_alias] refers to unresolved path [source.keyword]")
         .whenExecute(String.format(Locale.ROOT, "SELECT * FROM %s", index));
   }

opensearch/src/main/java/org/opensearch/sql/opensearch/data/type/OpenSearchDataType.java

@@ -14,6 +14,9 @@
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import org.apache.commons.lang3.EnumUtils;
+import org.opensearch.sql.common.error.ErrorCode;
+import org.opensearch.sql.common.error.ErrorReport;
+import org.opensearch.sql.common.error.QueryProcessingStage;
 import org.opensearch.sql.data.type.ExprCoreType;
 import org.opensearch.sql.data.type.ExprType;
 import org.opensearch.sql.exception.SemanticCheckException;
@@ -300,13 +303,22 @@ private static void validateAliasType(Map<String, OpenSearchDataType> result) {
             String originalPath = value.getOriginalPath().get();
             OpenSearchDataType target = result.get(originalPath);
             if (target == null) {
-              throw new SemanticCheckException(
-                  String.format(
-                      "Alias field [%s] refers to unresolved path [%s]. The alias path must point"
-                          + " to an existing field in the mapping; a text multi-field (e.g."
-                          + " \"%s.keyword\") or a removed/renamed field is not a valid alias"
-                          + " target.",
-                      key, originalPath, originalPath));
+              throw ErrorReport.wrap(
+                      new SemanticCheckException(
+                          String.format(
+                              "Alias field [%s] refers to unresolved path [%s].",
+                              key, originalPath)))
+                  .code(ErrorCode.FIELD_NOT_FOUND)
+                  .stage(QueryProcessingStage.ANALYZING)
+                  .location("while resolving alias fields in the index mapping")
+                  .context("alias_field", key)
+                  .context("alias_path", originalPath)
+                  .suggestion(
+                      "The alias path must point to an existing field in the mapping; a text"
+                          + " multi-field (e.g. \""
+                          + originalPath
+                          + ".keyword\") or a removed/renamed field is not a valid alias target.")
+                  .build();
             }
             result.put(key, new OpenSearchAliasType(originalPath, target));
           }

opensearch/src/test/java/org/opensearch/sql/opensearch/data/type/OpenSearchDataTypeTest.java

@@ -41,6 +41,9 @@
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.EnumSource;
 import org.junit.jupiter.params.provider.MethodSource;
+import org.opensearch.sql.common.error.ErrorCode;
+import org.opensearch.sql.common.error.ErrorReport;
+import org.opensearch.sql.common.error.QueryProcessingStage;
 import org.opensearch.sql.data.type.ExprCoreType;
 import org.opensearch.sql.data.type.ExprType;
 import org.opensearch.sql.exception.SemanticCheckException;
@@ -493,16 +496,23 @@ public void traverseAndFlatten_alias_to_unresolvable_path_throws_descriptive_err
             textKeywordType,
             "source_alias",
             new OpenSearchAliasType("source.keyword", OpenSearchDataType.of(MappingType.Invalid)));
-    SemanticCheckException keywordException =
+    ErrorReport keywordError =
         assertThrows(
-            SemanticCheckException.class,
-            () -> OpenSearchDataType.traverseAndFlatten(keywordAliasTree));
-    assertEquals(
-        "Alias field [source_alias] refers to unresolved path [source.keyword]. The alias path must"
-            + " point to an existing field in the mapping; a text multi-field (e.g."
-            + " \"source.keyword.keyword\") or a removed/renamed field is not a valid alias"
-            + " target.",
-        keywordException.getMessage());
+            ErrorReport.class, () -> OpenSearchDataType.traverseAndFlatten(keywordAliasTree));
+    assertAll(
+        () -> assertEquals(ErrorCode.FIELD_NOT_FOUND, keywordError.getCode()),
+        () -> assertEquals(QueryProcessingStage.ANALYZING, keywordError.getStage()),
+        () -> assertTrue(keywordError.getCause() instanceof SemanticCheckException),
+        () ->
+            assertEquals(
+                "Alias field [source_alias] refers to unresolved path [source.keyword].",
+                keywordError.getCause().getMessage()),
+        () -> assertEquals("source_alias", keywordError.getContext().get("alias_field")),
+        () -> assertEquals("source.keyword", keywordError.getContext().get("alias_path")),
+        () ->
+            assertTrue(
+                keywordError.getSuggestion().contains("\"source.keyword.keyword\"")
+                    && keywordError.getSuggestion().contains("not a valid alias target")));
 
     // Alias path targets a field that does not exist.
     Map<String, OpenSearchDataType> missingFieldTree =
@@ -511,15 +521,17 @@ public void traverseAndFlatten_alias_to_unresolvable_path_throws_descriptive_err
             textType,
             "col_alias",
             new OpenSearchAliasType("missing", OpenSearchDataType.of(MappingType.Invalid)));
-    SemanticCheckException missingException =
+    ErrorReport missingError =
         assertThrows(
-            SemanticCheckException.class,
-            () -> OpenSearchDataType.traverseAndFlatten(missingFieldTree));
-    assertEquals(
-        "Alias field [col_alias] refers to unresolved path [missing]. The alias path must point to"
-            + " an existing field in the mapping; a text multi-field (e.g. \"missing.keyword\") or"
-            + " a removed/renamed field is not a valid alias target.",
-        missingException.getMessage());
+            ErrorReport.class, () -> OpenSearchDataType.traverseAndFlatten(missingFieldTree));
+    assertAll(
+        () -> assertEquals(ErrorCode.FIELD_NOT_FOUND, missingError.getCode()),
+        () -> assertTrue(missingError.getCause() instanceof SemanticCheckException),
+        () ->
+            assertEquals(
+                "Alias field [col_alias] refers to unresolved path [missing].",
+                missingError.getCause().getMessage()),
+        () -> assertEquals("missing", missingError.getContext().get("alias_path")));
   }
 
   @Test