feat(knn): let a caller rebuild a batch KNN node with a new k - #9334
Merged
Merged
Conversation
A batch `KNNVectorDistanceExec` bounds every query's candidates by its own `k` and carries no enclosing top-k `SortExec`, so a plan rewriter that wants to widen the candidate set has nothing to move — `try_new_batch` is `pub(crate)` and `retain_vector` is private, so it can't rebuild the node either. `with_k` covers that: `k` feeds only the execute-time cut, never the schema or plan properties, so everything else carries over unchanged. Sophon's WAL union needs it to over-fetch the base arm on the unindexed batch shape, the way it already does for `ANNIvfBatchExec`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
![lance-gatekeeper[bot]](https://avatars.githubusercontent.com/in/4433141?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
✅ Gate recommendation: approve.
This focused builder changes only the batch node per-query candidate bound while preserving its child, schema, distance bounds, vector-retention mode, and plan properties. It retains the constructor zero-k validation and resets execution metrics for the rebuilt node.
lance-gatekeeper
Bot
added
the
K-approved
jackye1995
approved these changes
Sep 18, 2026
hamersaw
added a commit
that referenced
this pull request
Sep 18, 2026
) The `rustdoc` job on `main` has been failing since #9334 merged: https://github.com/lance-format/lance/actions/runs/35372502724/job/105689817498 `KNNVectorDistanceExec::with_k` is public but its doc comment linked to the crate-private `try_new_batch`, which `RUSTDOCFLAGS="-D warnings"` rejects via `rustdoc::private_intra_doc_links`. This refers to the constructor with plain code formatting instead. The failing check was already red on #9334 itself, it just is not a required check. Verified locally with `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps`, `cargo fmt --all -- --check`, and `cargo clippy --all --tests --benches -- -D warnings`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.1 <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
3 participants
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.
What
Adds
KNNVectorDistanceExec::with_k(k), returning the node rebuilt with a different per-queryk.Why
A batch
KNNVectorDistanceExecbounds every query's candidates by its ownkand carries no enclosing top-kSortExec— the plan is justKNNVectorDistance(queries=N, k=K)over a scan. A downstream rewriter that wants to widen the candidate set has nothing to move, and it can't rebuild the node either:try_new_batchispub(crate)andretain_vectoris a private field.kfeeds only the execute-time cut (execute_batch'sBatchKnnConfig), never the schema or plan properties, sowith_kcarries the rest of the node over unchanged. Zerokon a batch node is rejected, matchingtry_new_batch.This is the brute-force counterpart to the
ANNIvfBatchExecaccessors added in #9262. Sophon's WAL union over-fetches the base arm so a block-list can drop superseded rows and still leave ~k live ones; on the indexed batch shape it rebuildsANNIvfBatchExec, and on the unindexed batch shape it currently can't reach the cut at all.Testing
test_batch_with_k_rebuilds_the_cut_and_keeps_the_schemacovers the widenedk, the preserved schema/query_count/is_batch, that the original node is left alone, and the zero-krejection.🤖 Generated with Claude Code