Repository navigation
feat: support scan planning and pushdown for Java table providers - #119
wirybeaver wants to merge 2 commits into
Conversation
268a98f to
0b3a113
Compare
Expose scanWithArgs and filter capabilities as default TableProvider methods with immutable ScanArgs. Plan a lazy ExecutionPlan before execution while retaining existing full-schema providers; execute receives an explicit partition index. Forward DataFusion filter capabilities and preserve residual-filter/limit semantics without source-specific dependencies or DataFusion-core changes. Cover the Java/JNI/Arrow path with selective-source integration tests.
0b3a113 to
c1869ed
Compare
|
@andygrove Would you mind taking a review of this PR? Our team's service is in Java and needs to pass customized execution plan. |
andygrove
left a comment
There was a problem hiding this comment.
Thanks for working on this, and for turning pgwhalen's feedback around so quickly. The tests are thorough. They cover EXPLAIN planning without opening a reader, residual filters before LIMIT for inexact and unsupported filters, limit pushdown for exact filters, empty projection for COUNT(*), and independent scans under UNION ALL. I built it locally and clippy and the TableProvider* tests pass.
Could you update the PR description to match the current API? It still mentions ScanTableProvider, TableScanRequest, TableScan and planScan. The description becomes the squash commit message, so it would be good to have it describe scanWithArgs, ScanArgs and ExecutionPlan.
I left two inline comments on the API shape.
| * filter. Limits outside the non-negative Java {@code long} range are not forwarded; DataFusion | ||
| * still applies the query's limit. | ||
| */ | ||
| public record ScanArgs( |
There was a problem hiding this comment.
This exposes the generated LogicalExprNode as public API. That type tracks DataFusion's datafusion.proto for the bundled version, and its package is excluded from our Javadoc. Pushdown code that matches on BinaryExpr ops and literal variants, like the test's SelectiveSource, could break when we bump DataFusion. I think passing the proto is a reasonable first step, but should we say in table-provider.md that the expression format follows DataFusion's proto and may change between DataFusion versions? It would be good to agree on that compatibility story before this ships in a release.
There was a problem hiding this comment.
In my own java bindings I'd original made it a goal for the expression APIs (logical and physical) to use their own POJOs of sealed classes and records where it made sense, with the hope of the API feeling friendlier, and hiding the generated classes unless the caller wanted to pass them. I backed off voicing that goal when I saw the protos start to get exposed in this repo and I couldn't really explain why I thought it was important. You do highlight one possible compatibility issue that swings me back in the other direction.
There was a problem hiding this comment.
FWIW, here is my working draft of the "public API" agent instructions that I mentioned wanting to do many months ago. I have larger ambitions for it but tried to slim it down for what is realistic right now.
If that seems directionally correct and only require small tweaks, I'd be happy to open a proper PR. There are some minor divergences from the rules there which I could open up follow-up PRs for.
There was a problem hiding this comment.
Done. The guide and ScanArgs Javadoc explain that LogicalExprNode follows the bundled DataFusion version; providers should decline unfamiliar forms with UNSUPPORTED and retest on upgrade. I’d keep a stable Java expression model as a separate API discussion.
Leave scanWithArgs as the optional planning hook. Document that pushdown expressions follow the bundled DataFusion protobuf and that providers should decline unknown forms.
|
@andygrove The PR description now uses |
Which issue does this PR close?
Closes #118.
Rationale for this change
Java table providers currently receive no physical scan request. A selective source cannot choose an access path from pushed predicates, read only projected columns, or distinguish exact filtering from candidate pruning. Expose that existing DataFusion contract while keeping the Java/JNI binding thin and source-agnostic.
What changes are included in this PR?
Add
scanWithArgs(ScanArgs)andsupportsFiltersPushdowntoTableProvider. Providers can report pushdown support per filter and use the requested projection, filters and limit to build anExecutionPlanwithout opening a reader. The defaultscanWithArgsdefers to the existingscan(allocator)at execution time.DataFusion still owns residual filtering and limit placement. Providers may return the requested projected schema or the full registered schema. The adapter projects full-schema batches when needed, preserving row counts even for zero-column results. Source-specific access-path decisions stay in provider implementations; no storage SDK or DataFusion Rust-core change is introduced.
This remains a bounded, single-partition leaf-scan API, not a binding for arbitrary child-consuming physical operators.
Are these changes tested?
A Java/JNI/Arrow integration harness registers an in-memory selective source and inspects its planned requests and actual reads. EXPLAIN plans without opening the source; execution requests only the matching row and projected column. Inexact and unsupported predicates retain residual evaluation before LIMIT, exact predicates permit limit pushdown, and independent scans keep separate requests and readers. The existing full-schema provider path is exercised through the same native boundary.
The source is synthetic: this does not establish performance or correctness against an external storage service.
Are there any user-facing changes?
The new
TableProvidermethods,ScanArgsandExecutionPlanare additive.ExecutionPlan.execute(int partition, BufferAllocator allocator)receives partition0in this single-partition implementation. ExistingTableProviderandSimpleTableProviderimplementations need no changes. The provider guide documents projection, filter, limit, threading and reader-ownership contracts.