Skip to content

docs: add Understanding Comet Plans user guide page#4086

Merged
andygrove merged 7 commits intoapache:mainfrom
andygrove:docs/understanding-comet-plans
Apr 27, 2026
Merged

docs: add Understanding Comet Plans user guide page#4086
andygrove merged 7 commits intoapache:mainfrom
andygrove:docs/understanding-comet-plans

Conversation

@andygrove
Copy link
Copy Markdown
Member

@andygrove andygrove commented Apr 25, 2026

Which issue does this PR close?

Closes #2413.

Rationale for this change

We need to explain to users how to understand Comet plans, covering areas such as:

  • Difference between CometExchance and CometColumnarExchange.
  • Why some plans have a mix of Spark and Comet operators
  • How fallbacks work
  • The difference between the 4 different explain configs and when to use each one

What changes are included in this PR?

New user guide page.

How are these changes tested?

N/A


| Node | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `CometScan` | V1 Parquet file scan with native execution. |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are difference between CometScan and CometNativeScan? Some things are in JVM with CometScan?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just pushed an update to clarify. CometScan is a hybrid implementation with some back-and-forth between JVM and native code. From 0.15.0, the default is to use CometNativeScan, where execution is fully native.


As a result, a plan can mix three kinds of nodes:

- **`Comet*` nodes** that run natively in Rust (for example `CometProject`,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it actually makes me think should we call CometNative for native nodes, or rather CometJava for comet nodes running in JVM?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The LLMs all know about the current names though, so it could be confusing to rename at this point.

Some of the JVM nodes also involve native code, so it is more Hybrid.

Comment thread docs/source/user-guide/latest/understanding-comet-plans.md Outdated
Copy link
Copy Markdown
Contributor

@comphead comphead left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @andygrove

Co-authored-by: Oleks V <comphead@users.noreply.github.com>
@andygrove andygrove merged commit fc29bc3 into apache:main Apr 27, 2026
5 checks passed
@andygrove andygrove deleted the docs/understanding-comet-plans branch April 27, 2026 22:57
@andygrove
Copy link
Copy Markdown
Member Author

Merged. Thanks for the review @comphead and the question @nabuskey

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve documentation for configs related to explain/fallback

3 participants