Skip to content

Add explain support for analytics engine path#5275

Draft
ahkcs wants to merge 1 commit intoopensearch-project:feature/mustang-ppl-integrationfrom
ahkcs:pr/mustang-explain-observability
Draft

Add explain support for analytics engine path#5275
ahkcs wants to merge 1 commit intoopensearch-project:feature/mustang-ppl-integrationfrom
ahkcs:pr/mustang-explain-observability

Conversation

@ahkcs
Copy link
Collaborator

@ahkcs ahkcs commented Mar 26, 2026

Summary

Adds explain support for the analytics engine path (#5247). This is the second PR building on #5267 (query routing and execution handoff).

This PR covers Step 3 (explain) from the issue:

Step 3: Explain support [Done]

Return logical RelNode plan via _plugins/_ppl/_explain, include physical plan if Analytics engine provides QueryPlanExecutor.explain() API.

  • AnalyticsExecutionEngine.explain(): Returns logical plan via RelOptUtil.toString() with mode-aware SqlExplainLevel (SIMPLE/STANDARD/COST). Physical and extended plans are null since the analytics engine is not yet available.
  • RestUnifiedQueryAction.explain(): New entry point for explain requests on the analytics path. Formats response via JsonResponseFormatter with normalizeLf().
  • TransportPPLQueryAction routing: Checks isExplainRequest() for analytics indices and routes to unifiedQueryHandler.explain() instead of execute().

Explain response format

{
  "calcite": {
    "logical": "LogicalSystemLimit(...)\n  LogicalProject(ts=[$0], message=[$2])\n    LogicalFilter(condition=[=($1, 200)])\n      LogicalTableScan(table=[[opensearch, parquet_logs]])\n",
    "physical": null,
    "extended": null
  }
}

Physical plan will be populated when the analytics engine provides a QueryPlanExecutor.explain() API.

Changed Files

File Change
core/.../analytics/AnalyticsExecutionEngine.java Added explain(RelNode, ExplainMode, ...) method
plugin/.../rest/RestUnifiedQueryAction.java Added explain() entry point and createExplainListener()
plugin/.../transport/TransportPPLQueryAction.java Route explain requests for analytics indices
core/.../analytics/AnalyticsExecutionEngineTest.java Added 2 explain unit tests
integ-test/.../ppl/AnalyticsPPLIT.java Added 5 explain integration tests

Test plan

  • 2 unit tests -- explain logical plan, explain error propagation
  • 5 integration tests -- explain response structure (JSON shape, null physical/extended), project+scan, filter, aggregation, sort plans

opensearch-project#5247)

Add explain support for the analytics engine path:

- AnalyticsExecutionEngine.explain(RelNode, ExplainMode, ...): returns
  logical plan via RelOptUtil.toString() with mode-aware SqlExplainLevel
  (SIMPLE/STANDARD/COST). Physical and extended plans are null since the
  analytics engine is not yet available.

- RestUnifiedQueryAction.explain(): new entry point for explain requests,
  delegates to AnalyticsExecutionEngine.explain() with ExplainMode.STANDARD.
  Response formatted via JsonResponseFormatter with normalizeLf().

- TransportPPLQueryAction: routes explain requests for analytics indices
  to unifiedQueryHandler.explain() instead of unifiedQueryHandler.execute().

Integration tests (AnalyticsPPLIT):
- testExplainResponseStructure: verifies JSON shape (calcite.logical,
  calcite.physical=null, calcite.extended=null)
- testExplainProjectAndScan: LogicalProject + LogicalTableScan + table name
- testExplainFilterPlan: LogicalFilter with condition value
- testExplainAggregationPlan: LogicalAggregate with COUNT()
- testExplainSortPlan: LogicalSort

Unit tests (AnalyticsExecutionEngineTest):
- explainRelNode_returnsLogicalPlan
- explainRelNode_errorPropagation

Signed-off-by: Kai Huang <kaihuang@amazon.com>
Signed-off-by: Kai Huang <ahkcs@amazon.com>
@github-actions
Copy link
Contributor

Failed to generate code suggestions for PR

@ahkcs ahkcs added PPL Piped processing language enhancement New feature or request labels Mar 26, 2026
@ahkcs ahkcs changed the title [Mustang] Add explain support for analytics engine path Add explain support for analytics engine path Mar 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request PPL Piped processing language

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant