Minimal query-aware statistics request hooks (extracted from #21996)#22300
Draft
adriangb wants to merge 6 commits into
Draft
Minimal query-aware statistics request hooks (extracted from #21996)#22300adriangb wants to merge 6 commits into
adriangb wants to merge 6 commits into
Conversation
`TableScan::try_new` takes five positional arguments and bare
`TableScan { .. }` struct literals are scattered across the codebase,
making both fragile to field additions.
Introduce `TableScanBuilder` (with `From<TableScan>`, so an existing
scan can be decomposed, tweaked, and rebuilt) and move the
schema-derivation logic into `build()`. `TableScan::try_new` is now
deprecated and delegates to the builder; all in-tree callers are
migrated to the builder. Pure refactor, no behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a query-aware statistics vocabulary to `datafusion-expr-common`: - `StatisticsRequest` — a statistic a caller would like a provider to supply if it can do so cheaply (Min/Max/NullCount/DistinctCount/Sum/ ByteSize per column, plus RowCount and TotalByteSize). - `StatisticsValue` — the response value paired 1:1 with a request. - `SatisfiedStatistics` — a sparse `HashMap<StatisticsRequest, StatisticsValue>` of provider answers. These are intentionally just a vocabulary; nothing in DataFusion populates or consumes them yet. They are re-exported via `datafusion_expr::statistics`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add an advisory `statistics_requests: Vec<StatisticsRequest>` field to `TableScan`. A custom optimizer rule can attach the statistics the surrounding plan shape would benefit from (e.g. Min/Max for sort keys) via `TableScan::with_statistics_requests` or the new `TableScanBuilder::with_statistics_requests`; the physical planner will thread them into the table provider (next commit). The field is empty by default and DataFusion's own rules never populate it. `Debug`/`PartialEq`/`Eq`/`Hash`/`PartialOrd` for `TableScan` are left unchanged — it is advisory metadata, not part of plan identity. `map_expressions` in `tree_node.rs` is rewritten to rebuild `TableScan` via `..scan` instead of an exhaustive destructure, so it carries this (and any future) field through untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a `statistics_requests` field to `ScanArgs` (with `with_statistics_requests` / `statistics_requests` accessors) and have the physical planner thread `TableScan::statistics_requests` into it. This completes the request-side path: a custom optimizer rule annotates `TableScan`, and the request reaches a custom `TableProvider` in `scan_with_args`. DataFusion's own providers ignore the field; the default `ScanArgs` value is an empty slice. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a self-contained integration test that plays both external roles: a custom `OptimizerRule` annotates each `TableScan` with `StatisticsRequest`s, and a custom `TableProvider` records the `ScanArgs::statistics_requests` it receives in `scan_with_args`. This demonstrates the request-side hooks are sufficient to build the feature entirely outside of DataFusion. A second test confirms that without such a rule the provider sees an empty request list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
logical-expr
|
Thank you for opening this pull request! Reviewer note: cargo-semver-checks reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch). Details |
`cargo doc -D warnings` (CI) rejected two intra-doc links: - `crate::TableProvider` in `datafusion-expr` — `TableProvider` lives in `datafusion-catalog` and is not reachable from `datafusion-expr`; demoted to a plain code span. - `Self::statistics_requests` on `ScanArgs` was ambiguous between the private field and the public accessor; disambiguated to `Self::statistics_requests()`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
datafusion.execution.collect_statisticson wide tables #21624This is not a replacement for #21996 — it is a minimal subset of it, carved out so the feature can be discussed/merged in smaller pieces.
Rationale for this change
#21996 ("Query-aware statistics requests via ScanArgs / ScanResult") is a full vertical slice: new statistics types, request threading optimizer → planner → provider, a built-in
RequestStatisticsoptimizer rule, and a consumer integration (FilePruner/ListingTable).This PR extracts only the framework hooks — just enough that the rest can be implemented entirely outside of DataFusion. A third party can write their own optimizer rule to derive statistics requests, and their own
TableProviderto consume them, without DataFusion shipping any rule or consumer of its own.In stock DataFusion nothing observable changes: no rule populates the new field, and the built-in providers ignore it.
What changes are included in this PR?
Five small, independently-reviewable commits:
refactor: add TableScanBuilder, deprecate TableScan::try_new—TableScan::try_newtakes five positional args and bareTableScan { .. }literals are fragile to field additions. IntroduceTableScanBuilder(withFrom<TableScan>), move schema derivation intobuild(), deprecatetry_new(delegates to the builder), migrate all in-tree callers. Pure refactor.feat: add StatisticsRequest / StatisticsValue / SatisfiedStatistics— new public vocabulary types indatafusion-expr-common::statistics. Nothing consumes them yet.feat: add TableScan::statistics_requests field— an advisoryVec<StatisticsRequest>onTableScan, settable viaTableScan::with_statistics_requests/TableScanBuilder. Empty by default; DataFusion's own rules never populate it.feat: thread statistics requests into ScanArgs—ScanArgsgainsstatistics_requests; the physical planner threadsTableScan::statistics_requestsinto it so the request reachesTableProvider::scan_with_args.test: e2e statistics-request flow via a custom optimizer rule— an integration test playing both external roles.Deliberately left out vs #21996: the built-in
RequestStatisticsoptimizer rule, theFilePruner/ListingTableconsumer integration, thePartitionedFile::satisfied_statsper-file response field, andStatisticsValue::Distribution(which would depend on the now-deprecatedDistributiontype).Are these changes tested?
Yes:
datafusion-expr-common: a unit test thatStatisticsRequestis hashable / usable as aHashMapkey.datafusion/core/tests/user_defined/statistics_requests.rs: an end-to-end integration test where a customOptimizerRuleannotatesTableScanand a customTableProviderasserts the requests reachscan_with_args— plus a test that without such a rule the provider sees an empty request list.datafusion-expr/datafusion-optimizer/datafusion-prototests pass against theTableScanBuilderrefactor.Are there any user-facing changes?
Yes — this needs the
api changelabel:StatisticsRequest,StatisticsValue,SatisfiedStatistics(re-exported viadatafusion_expr::statistics).TableScanBuilder;TableScan::try_newis deprecated (still works, delegates to the builder).TableScangains a new public fieldstatistics_requests— this breaks exhaustiveTableScan { .. }struct literals downstream (the recommended fix isTableScanBuilder).ScanArgsgainswith_statistics_requests/statistics_requests.🤖 Generated with Claude Code