Add optional query bit size hint to KnnSearchStrategy.Hnsw

[arup-chauhan]

This PR introduces an optional query bit-size hint for KnnSearchStrategy.Hnsw as a first incremental step toward #15614.

I intentionally limited the scope to search-strategy API plumbing and tests to keep risk low.
Default behavior remains unchanged: the new hint is metadata-only in this PR and does not alter scoring yet.

Changes

• Added optional queryBitSizeHint to KnnSearchStrategy.Hnsw.
• Kept backward compatibility by preserving the existing constructor and adding an overload:
  • Hnsw(int filteredSearchThreshold)
  • Hnsw(int filteredSearchThreshold, Integer queryBitSizeHint)
• Added validation for the hint (> 0 when non-null).
• Added getter: queryBitSizeHint().
• Updated equals / hashCode for Hnsw to include the new hint.
• Updated KnnSearchStrategy.Patience constructors to support hint passthrough.
• Updated HnswQueueSaturationCollector#getSearchStrategy() to preserve and forward the hint when wrapping strategies.
• Added new tests in TestKnnSearchStrategy to cover:
  • default/no-hint behavior
  • constructor with hint
  • hint validation
  • equals/hashCode behavior
  • hint preservation across seeded/patience wrapping paths

Validation

• ./gradlew -p lucene/core compileJava
• ./gradlew -p lucene/core test --tests TestKnnSearchStrategy
• ./gradlew -p lucene/core check

Only tweak I made: removed “(after formatting fix)” since it passes now.

[arup-chauhan]

Hey @benwtrent

Implemented the first incremental step by adding an optional queryBitSizeHint to KnnSearchStrategy.Hnsw.

I’ve preserved backward compatibility, forwarded the hint through Patience / seeded wrapping paths, and added focused strategy tests. This PR intentionally does not change scoring behavior.

Next, I plan to wire the hint into the vector reader/scorer plumbing, and then follow up with a small PR that uses the hint for query-bit-aware behavior in the scalar-quantized scoring path.

Looking forward to your feedback!

[benwtrent]

I wonder what @mccullocht thinks? I know when we were discussing the new scalar formats, we stuck to a static query bits for doc vectors for simplicity.

I am on the fence on the complexity this potentially adds for users. Basically, my concern is that certain datasets work very well with just single bit or 2 bit queries vs. single bit quantized vectors. This gives 2x or 4x better vector ops throughput with almost zero change in recall.

I also think we want the ability to "refine" the query scores by increasing the bits on a subset of vectors. Which hopefully users don't have to directly access.

[mccullocht]

This API is probably fine for the described purpose but I'm skeptical about how useful this will be. Recall improvements diminish pretty quickly when increasing the query bit rate without increasing the doc bit rate. I'm optimistic that we could do more to improve recall and performance without exposing this kind of parameter.

To obey the proposed API we would need to be able to compare two vectors of different bit rates for any pair of bit rates up to, say, 8 bits/dim. Up to somewhere around 4-8 comparisons/dimension the transpose + popcount strategy that we employ for bit and dibit works, but once the number of comparisons grows larger than that it starts to become cheaper to perform a dot product, and how well that will work depends a lot on how the vectors are packed. The current 1-bit packing scheme in particular would be difficult to compare to other bit rate vectors because of how hard it would be to unpack into the same dimension order as something else. This problem also exists if you look at extending the doc vector with quantized residual as described in the LVQ paper.

I have another idea that is inspired by placing statistical bounds on estimated distance as described in the RaBitQ paper -- the idea is that if a minSimilarity parameter was passed to score() the scorer might be able to eliminate certain candidates after examining only 1 bit of a 4 bit query vector. I'll file an issue for this once I have a better handle on the math.

[arup-chauhan]

Hey @mccullocht @benwtrent,

Thanks, this is super helpful context.

I agree that recall gains from increasing query bits alone may taper quickly, and that cross-bit-rate comparisons can get expensive/packing-dependent.

In this PR, I only added metadata/API plumbing (no scoring behavior change yet), but your points are exactly the risks for follow-up use.

I’m happy to keep this scoped as incremental plumbing and treat any query-bit-aware scoring work as a follow-up, backed by evidence (benchmarks, recall, and complexity tradeoffs), potentially behind internal strategy decisions so users don’t need to tune low-level parameters directly.

The minSimilarity-based early-elimination idea sounds very promising. Looking forward to the issue.

[github-actions]

This PR has not had activity in the past 2 weeks, labeling it as stale. If the PR is waiting for review, notify the dev@lucene.apache.org list. Thank you for your contribution!