andygrove opened a new pull request, #4086:
URL: https://github.com/apache/datafusion-comet/pull/4086
## Which issue does this PR close?
Closes #2413.
## Rationale for this change
The four explain/fallback configs (`spark.comet.explainFallback.enabled`,
`spark.comet.logFallbackReasons.enabled`, `spark.comet.explain.format`,
`spark.comet.explain.native.enabled`) currently only have brief one-line
descriptions in the auto-generated config table, and the existing "Explain
Plan" section in the Tuning Guide only documents the Spark 4.0
`extendedExplainProviders` integration. There is no single place that
explains how the four configs differ, where their output appears, and how
they interact with fallback. There is also no guide to the `Comet*`
operator names that appear in plans, which makes it hard for new users to
read a Comet plan, understand the difference between `CometExchange` and
`CometColumnarExchange`, or know what the various columnar/row transition
nodes do.
## What changes are included in this PR?
- New user guide page `understanding-comet-plans.md` covering:
- How to read a Comet plan (node prefixes, transitions, exchange types).
- What fallback means and common reasons for it.
- A comparison table for the four explain/fallback configs, including
where each writes its output and when to use it.
- A Comet operator reference grouped by scans, native execution
operators, JVM-side operators, shuffle, and columnar/row transitions.
- Detailed notes on `CometExchange` vs `CometColumnarExchange`, and on
the multiple `ColumnarToRow` / `RowToColumnar` implementations.
- Removed the "Explain Plan" / "Extended Explain" subsections from the
Tuning Guide and replaced them with a one-line link to the new page.
- Added the new page to the user guide TOC in `index.rst`.
## How are these changes tested?
Documentation-only change. Verified the new page renders by inspecting
the Markdown directly; no behavior changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
