Lucene: define and validate CAGRA parameter boundaries - #2516
Open
shaunakkapur wants to merge 10 commits into
Open
Lucene: define and validate CAGRA parameter boundaries#2516shaunakkapur wants to merge 10 commits into
shaunakkapur wants to merge 10 commits into
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Contributor
Author
|
/ok to test efb837a |
cjnolet
added
improvement
shaunakkapur
changed the title
Contributor
Author
|
/ok to test a405e39 |
Contributor
Author
|
/ok to test 9bdd04b |
1 similar comment
Contributor
Author
|
/ok to test 9bdd04b |
Contributor
Author
|
/ok to test 558635f |
shaunakkapur
marked this pull request as ready for review
August 28, 2026 02:12
dantegd
requested changes
Aug 28, 2026
dantegd
left a comment
dantegd
left a comment
Contributor
There was a problem hiding this comment.
Great to see this PR! Just had a few comments
- Scope graphDegree <= intermediateGraphDegree validation to CUSTOM strategy in AcceleratedHNSWParams/GPUSearchParams; HEURISTIC derives both degrees and ignores the configured pair, so previously a valid HEURISTIC config could fail to build over values that were never used. Remove the resulting workaround setter from TestSegmentMaxConnConsistency and add regression tests for both the CUSTOM enforcement and the HEURISTIC no-op case. - Re-validate the SINGLE_CTA effective iTopK limit against the value actually sent to native CAGRA in CuVS2510GPUVectorsReader, not just the value checked at GPUKnnFloatVectorQuery construction time: the filtered per-segment fallback path can raise topK further based on filter cardinality after construction, so a config valid at construction could still send an out-of-range value to native CAGRA. Add a regression test reproducing this exact scenario. - Stop presenting GPUKnnFloatVectorQuery's MAX_ITOPK/MAX_SEARCH_WIDTH as universally valid native ranges in the README and tests. Only the lower bound of 1 and the SINGLE_CTA iTopK maximum of 512 are genuine native limits; other upper bounds depend on the resolved algorithm, max_iterations, graph degree, and dataset size, none of which are known at query-construction time. Document that native CAGRA rejects unsupported combinations itself (e.g. MULTI_CTA's 25-bit traversal hash-table limit), and add a test that builds a real native search plan to confirm this for an oversized MULTI_CTA searchWidth. Also correct the README's HEURISTIC description: AcceleratedHNSWParams derives both degrees from maxConn/beamWidth, while GPUSearchParams passes the configured graphDegree into the dataset heuristic and derives the rest from it. Signed-off-by: Shaunak Kapur <shaunakk@nvidia.com>
- TestNativeSearchPlanBoundaryRejection: exercise AUTO (not an explicit MULTI_CTA) for the oversized searchWidth case, matching the reviewer's exact "normal one-query AUTO search resolves to MULTI_CTA" scenario, and assert the native exception message names the hash_bitlen/25 limit so an unrelated native/CUDA failure can't make the test pass. Also document why this class deliberately does not add an equivalent MAX_ITOPK case: empirically, iTopK = Integer.MAX_VALUE does not fail fast like an oversized searchWidth -- it hangs indefinitely inside the native call instead, which would make a test asserting on it unsafe to run in CI. - TestFilteredSingleCtaITopKValidation: assert the rejection message names SINGLE_CTA and the specific 512/513 values, confirming the post-filter re-validation fired rather than some unrelated argument check. - README: clarify that most parameter checks run at construction time but the SINGLE_CTA iTopK limit is additionally re-checked at search time, and that only intermediateGraphDegree is ignored under HEURISTIC for GPUSearchParams (graphDegree is passed into the dataset-size heuristic, not ignored). Verified locally: full compile, 34/34 relevant tests pass (including both native GPU-backed integration tests), spotless clean. Signed-off-by: Shaunak Kapur <shaunakk@nvidia.com>
The javadoc and README claimed native CAGRA rejects any oversized itopk_size/searchWidth combination with a clear exception. Measurement shows that only holds below a threshold: above roughly iTopK 1e9 the native hash-table sizing loop fails to terminate and the search hangs instead of erroring. Correct that claim, stop implying MAX_ITOPK is a usable maximum, and point at NVIDIA#2523 which tracks the native defect. Documentation only; no behaviour change. Signed-off-by: Shaunak Kapur <shaunakk@nvidia.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.
Summary
Define and document boundaries for all five Lucene CAGRA parameter families: writer threads, intermediate graph degree, graph degree, iTopK, and search width.
Validate individual build parameter ranges when public builder setters are called. Validate at build time that graphDegree does not exceed intermediateGraphDegree, independent of setter order.
Validate search parameters when GPUKnnFloatVectorQuery is constructed, including the native SINGLE_CTA iTopK limit and the numeric safety limit for search width.
Add focused minimum, maximum, invalid range, cross field relationship, and search algorithm coverage.
Testing
Closes #2450