Make HNSW search beam width configurable

[fh-ms]

Summary

The HNSW search path enforces a minimum beam width (HNSW efSearch) so that the top-k stays stable across different requested k values — without it, search(q, 5) can return a different top-5 than the first five entries of search(q, 50).

This PR turns the floor into two knobs:

1. VectorIndexConfiguration.minSearchBeamWidth() — index-level floor (default 100, preserves current behavior). Set to 1 to disable the floor entirely.
2. VectorIndex.search(float[] query, int k, int searchBeamWidth) (plus the matching search(E entity, int k, int searchBeamWidth) default) — per-query override. The effective beam width becomes max(k, searchBeamWidth) for that call, bypassing the config floor.

Search-time beam width (HNSW efSearch) is conceptually distinct from the existing beamWidth() (HNSW efConstruction, construction only), so it's a separate property rather than a reinterpretation of the existing one.

Changes

• VectorIndexConfiguration: new minSearchBeamWidth() getter + builder method, default 100.
• VectorIndex.Default: computeRerankK now reads from the configuration. Search dispatch refactored so rerankK flows as a parameter into searchInMemoryIndex / searchDiskIndex / searchIncremental — the floor logic lives in one place.
• New public search(..., int searchBeamWidth) overloads on VectorIndex.
• AsciiDoc updates in configuration.adoc, index.adoc, advanced.adoc — new parameter, clarified construction-vs-search wording, and the PQ two-phase reranking section now shows max(2 * k, minSearchBeamWidth) instead of just 2 * k.

Compatibility

• Old persisted VectorIndexConfiguration.Default instances deserialize with minSearchBeamWidth = 0, which collapses to rerankK = k — safe, no migration required.

[Copilot]

Pull request overview

Adds a minimum search “beam width” (candidate exploration) to decouple HNSW search effort from the requested k, aiming to make top-k results stable when callers vary k.

Changes:

• Introduces a minimum rerankK for HNSW search to ensure sufficient exploration for small k.
• Updates in-memory, disk, incremental, and PQ-rerank search paths to use rerankK.
• Adds a regression test asserting top-5 stability between k=5 and k=50.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
gigamap/jvector/src/main/java/org/eclipse/store/gigamap/jvector/VectorIndex.java	Computes and applies a minimum rerankK; updates search paths and incremental merging behavior.
gigamap/jvector/src/main/java/org/eclipse/store/gigamap/jvector/PQCompressionManager.java	Threads rerankK into PQ rerank flow; ensures candidate count meets the minimum exploration level.
gigamap/jvector/src/test/java/org/eclipse/store/gigamap/jvector/VectorIndexTest.java	Adds a test to verify top-5 consistency across different requested k values.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.