Initial implementation of report-builder interface

[Swiddis]

Description

Well, this is turning out quite long.

The fundamental idea of this PR is to add a lot more context to error messages. For example, take this bad query:

source = big5
| eval range_bucket = case(
   `metrics.size` < -10, 'range_1',
   `metrics.size` >= -10 and `metrics.size` < 10, 'range_2',
   `metrics.size` >= 10 and `metrics.size` < 100, 'range_3',
   `metrics.size` >= 100 and `metrics.size` < 1000, 'range_4',
   `metrics.size` >= 1000 and `metrics.size` < 2000, 'range_5',
   `metrics.size` >= 2000, 'range_6')
| stats count() by range_bucket, span(`@timestamp`, 1h) as auto_span
| sort + range_bucket, + auto_spa

Now there's more context, provided at various layers:

{
  "error": {
    "context": {
      "stage": "analyzing",
      "stage_description": "Validating the query"
    },
    "details": "Field [auto_spa] not found.",
    "location": [
      "checking if fields and indices exist"
    ],
    "code": "FIELD_NOT_FOUND",
    "type": "IllegalArgumentException"
  },
  "status": 400
}

A lot of this PR in terms of line count is just patching specific places where tests are asserting errors behave in specific ways. The core of the PR is ErrorReport and StageErrorHandler which adds utilities for incrementally building detailed errors, QueryService where we hook up the outer shell of the stage handlers, and RestPPLQueryAction where we handle and present the errors. Simple tests are in error_reports.yml, as well as doctest and various other scattered tests.

The enhancements aren't super complete in this PR as the emphasis is scaffolding (and the integration work + fixing tests is already quite significant), for the most part the changes are backwards compatible in normal cases. The type, details, and status fields are in the same spots and by default pull from the underlying exception.

Related Issues

#5261, #4919

Check List

• New functionality includes testing.
• New functionality has been documented.
• New functionality has javadoc added.
• New functionality has a user manual doc added.
• New PPL command checklist all confirmed.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff or -s.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

PR Code Analyzer ❗

AI-powered 'Code-Diff-Analyzer' found issues on commit d25006e.

Path	Line	Severity	Description
integ-test/src/test/java/org/opensearch/sql/datasource/DataSourceEnabledIT.java	153	low	Debug logging statements (`System.err.println`) printing full HTTP response bodies were added to a test helper method. While in a test file, this could inadvertently log sensitive response payloads (tokens, credentials) during CI runs where stderr is captured and stored. Appears to be accidental debug code left uncommitted rather than malicious intent.
core/src/main/java/org/opensearch/sql/calcite/utils/CalciteToolsHelper.java	437	low	The `enrichErrorsForSpecialCases` method extracts and places the raw Calcite query plan text (including SQL AST fragments) into the `context` map under key `plan`, which is subsequently serialized directly into the client-facing API error response via `ErrorReport.toJsonMap()` → `ErrorMessage.getErrorAsJson()`. This leaks internal query plan structure to external API consumers. The intent appears to be improving debuggability, not malicious exfiltration, but represents unintended information disclosure.

The table above displays the top 10 most important findings.

Total: 2 | Critical: 0 | High: 0 | Medium: 0 | Low: 2

---

Pull Requests Author(s): Please update your Pull Request according to the report above.

Repository Maintainer(s): You can bypass diff analyzer by adding label skip-diff-analyzer after reviewing the changes carefully, then re-run failed actions. To re-enable the analyzer, remove the label, then re-run all actions.

---

⚠️ Note: The Code-Diff-Analyzer helps protect against potentially harmful code patterns. Please ensure you have thoroughly reviewed the changes beforehand.

Thanks.

[github-actions]

Failed to generate code suggestions for PR

[Swiddis]

The error enrichment logic extracts the raw SQL query plan string from internal exception messages and...

In context, this is pulling details out of a potentially very fuzzy Calcite error. The error logic without any of this ultimately returns the plan with a message resembling "Failed to prepare plan: [blob]." The plan is provided as context as the innermost error might be weird and only apply to one node, e.g. CalciteEnumerableNestedAggregate having a problem means nothing without access to the plan containing said aggregate. In OSD this plan probably won't be presented to users directly.

Any details about our internal implementation can be easily scrutinized by navigating to https://github.com/opensearch-project/sql in a recent version of Netscape Navigator.

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

Failed to generate code suggestions for PR