From e241fdaf98891934a2a4da74d5af87e0f091563f Mon Sep 17 00:00:00 2001 From: lerman25 Date: Wed, 11 Nov 2026 19:04:48 +0200 Subject: [PATCH 1/2] Cache NaviX filter decisions across query batches --- docs/navix-poc.md | 10 ++++- .../algorithms/hnsw/hnsw_batch_iterator.h | 17 +++++-- tests/unit/test_navix.cpp | 45 ++++++++++++++++++- 3 files changed, 66 insertions(+), 6 deletions(-) diff --git a/docs/navix-poc.md b/docs/navix-poc.md index e7e804f47..34ed5f92d 100644 --- a/docs/navix-poc.md +++ b/docs/navix-poc.md @@ -25,6 +25,10 @@ conservative eligibility. It is not the paper's exact membership-set implementat rejected initial seed can navigate without tightening the result bound. - Retain the frontier/extras/visited list across batches. Bound ties remain on the frontier for the next batch so equal-distance candidates are not silently dropped. +- Cache NO/MAYBE callback decisions by internal ID across batches. The cache allocates + one byte per graph node on the first check (about 1 MB for one million nodes), using + the iterator allocator. Reset invalidates decisions and retains capacity for reuse; + freeing the iterator releases the cache. Ordinary HNSW queries do not allocate it. - Reuse O(D) scratch space, copy one adjacency list under one node lock, and poll the query timeout in both hops. There is no membership bitmap, extra seed, disconnected-component recovery, or fallback scan. @@ -34,10 +38,12 @@ fail it. Exhaustion can return fewer than k, even when more eligible documents e Increasing ef cannot repair all disconnected filtered neighborhoods. The tiered brute-force frontend applies the same callback before scoring. Counters cover -base-layer expansion and frontend scoring; distance counts exclude upper-layer descent +base-layer expansion and frontend scoring. HNSW filter checks/rejections count actual +callback evaluations, excluding cache hits; distance counts exclude upper-layer descent and the initial seed distance. Counters accumulate across calls and resets. Top-k and range APIs do not activate this POC; use the batch API. The integration validates only unquantized, single-value FLOAT32 RAM HNSW. `test_navix` covers rejected seeds/branches, shared second-hop nodes, equal-distance -batch continuation, strategy selection, timeout/reset, and frontend filtering/reset. +batch continuation, strategy selection, timeout/reset, frontend filtering/reset, cached +NO/MAYBE decisions, reset invalidation, and isolation between query iterators. diff --git a/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h b/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h index 4fe8400f7..5e88cb230 100644 --- a/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h +++ b/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h @@ -33,6 +33,8 @@ class HNSW_BatchIterator : public VecSimBatchIterator { using candidatesMinHeap = vecsim_stl::min_priority_queue; VecSimNavixParams navix{}; + enum class NavixMatch : uint8_t { Unknown, No, Maybe }; + vecsim_stl::vector navix_filter_cache; vecsim_stl::vector navix_direct, navix_second; vecsim_stl::vector navix_matches; vecsim_stl::vector> navix_branches; @@ -83,9 +85,10 @@ HNSW_BatchIterator::HNSW_BatchIterator( std::shared_ptr allocator) : VecSimBatchIterator(query_vector, queryParams ? queryParams->timeoutCtx : nullptr, std::move(allocator)), - index(index), depleted(false), navix_direct(this->allocator), navix_second(this->allocator), - navix_matches(this->allocator), navix_branches(this->allocator), - top_candidates_extras(this->allocator), candidates(this->allocator) { + index(index), depleted(false), navix_filter_cache(this->allocator), + navix_direct(this->allocator), navix_second(this->allocator), navix_matches(this->allocator), + navix_branches(this->allocator), top_candidates_extras(this->allocator), + candidates(this->allocator) { if (queryParams) navix = queryParams->navix; @@ -107,9 +110,16 @@ template bool HNSW_BatchIterator::navixMayMatch(idType id) { if (index->isMarkedDeleted(id)) return false; + // The NaviX contract keeps internal IDs and the filter stable until reset. + if (navix_filter_cache.empty()) + navix_filter_cache.resize(index->indexSize(), NavixMatch::Unknown); + auto &cached = navix_filter_cache[id]; + if (cached != NavixMatch::Unknown) + return cached == NavixMatch::Maybe; if (navix.stats) ++navix.stats->filterChecks; bool pass = navix.mayMatch(navix.context, index->getExternalLabel(id)) != 0; + cached = pass ? NavixMatch::Maybe : NavixMatch::No; if (!pass && navix.stats) ++navix.stats->filterRejected; return pass; @@ -397,6 +407,7 @@ template void HNSW_BatchIterator::reset() { this->resetResultsCount(); this->depleted = false; + navix_filter_cache.clear(); // Reset the visited nodes handler. this->visited_tag = this->visited_list->getFreshTag(); diff --git a/tests/unit/test_navix.cpp b/tests/unit/test_navix.cpp index 41c8a02b5..7622c7024 100644 --- a/tests/unit/test_navix.cpp +++ b/tests/unit/test_navix.cpp @@ -10,6 +10,7 @@ #include "VecSim/vec_sim.h" #include "VecSim/algorithms/hnsw/hnsw_single.h" #include "VecSim/query_result_definitions.h" +#include #include namespace { @@ -20,6 +21,7 @@ struct Fixture { HNSWIndex *graph; idType seed; std::set allowed; + std::map filter_calls; VecSimNavixStats stats{}; VecSimQueryParams params{}; float query = 0; @@ -42,7 +44,9 @@ struct Fixture { graph->getElementLevelData(i, 0).numLinks = 0; params.hnswRuntimeParams.efRuntime = 1; params.navix = {[](void *ctx, size_t label) { - return static_cast(ctx)->allowed.contains(label) ? 1 : 0; + auto *fixture = static_cast(ctx); + ++fixture->filter_calls[label]; + return fixture->allowed.contains(label) ? 1 : 0; }, this, &stats, false}; } @@ -112,6 +116,45 @@ TEST(Navix, AdaptiveModesAndNoMatches) { } } +TEST(Navix, CachesBothDecisionsAcrossBatchesAndInvalidatesOnReset) { + for (bool blind : {false, true}) { + Fixture f; + f.sparseGraph(); + f.params.navix.forceBlind = blind; + auto *it = f.iterator(); + EXPECT_EQ(f.drain(it), f.allowed); + EXPECT_EQ(f.filter_calls.size(), 5u); + for (const auto &[label, calls] : f.filter_calls) + EXPECT_EQ(calls, 1u) << label; + EXPECT_EQ(f.stats.filterChecks, 5u); + EXPECT_EQ(f.stats.filterRejected, 3u); + + VecSimBatchIterator_Reset(it); + f.allowed.erase(labelBase + f.node(3)); + f.accept(1); + EXPECT_EQ(f.drain(it), f.allowed); + for (const auto &[label, calls] : f.filter_calls) + EXPECT_EQ(calls, 2u) << label; + EXPECT_EQ(f.stats.filterChecks, 10u); + EXPECT_EQ(f.stats.filterRejected, 6u); + VecSimBatchIterator_Free(it); + } +} + +TEST(Navix, FilterCacheIsLocalToEachIterator) { + Fixture f; + f.sparseGraph(); + auto *first = f.iterator(); + auto *second = f.iterator(); + EXPECT_EQ(f.drain(first), f.allowed); + EXPECT_EQ(f.drain(second), f.allowed); + EXPECT_EQ(f.filter_calls.size(), 5u); + for (const auto &[label, calls] : f.filter_calls) + EXPECT_EQ(calls, 2u) << label; + VecSimBatchIterator_Free(first); + VecSimBatchIterator_Free(second); +} + TEST(Navix, TimeoutInsideSecondHopThenReset) { Fixture f; f.sparseGraph(); From cb2f3a5f67b4d22099d3b70610fe3d4613ca671a Mon Sep 17 00:00:00 2001 From: Omer Lerman <58445352+lerman25@users.noreply.github.com> Date: Wed, 11 Nov 2026 19:23:46 +0200 Subject: [PATCH 2/2] Handle appended backend nodes without reading mutable index size --- docs/navix-poc.md | 12 ++++--- .../algorithms/hnsw/hnsw_batch_iterator.h | 6 ++-- tests/unit/test_navix.cpp | 33 +++++++++++++++++-- 3 files changed, 41 insertions(+), 10 deletions(-) diff --git a/docs/navix-poc.md b/docs/navix-poc.md index 34ed5f92d..e0aeed263 100644 --- a/docs/navix-poc.md +++ b/docs/navix-poc.md @@ -25,10 +25,12 @@ conservative eligibility. It is not the paper's exact membership-set implementat rejected initial seed can navigate without tightening the result bound. - Retain the frontier/extras/visited list across batches. Bound ties remain on the frontier for the next batch so equal-distance candidates are not silently dropped. -- Cache NO/MAYBE callback decisions by internal ID across batches. The cache allocates - one byte per graph node on the first check (about 1 MB for one million nodes), using - the iterator allocator. Reset invalidates decisions and retains capacity for reuse; - freeing the iterator releases the cache. Ordinary HNSW queries do not allocate it. +- Cache NO/MAYBE callback decisions by internal ID across batches. The cache grows + through the highest checked ID using the iterator allocator: one byte per ID slot, + plus vector capacity slack (one million slots hold 1 MB of decisions). Reset invalidates + decisions and retains capacity for reuse; freeing the iterator releases the cache. + Ordinary HNSW queries do not allocate it. New backend nodes from background migration + are handled without reading the concurrently changing index size. - Reuse O(D) scratch space, copy one adjacency list under one node lock, and poll the query timeout in both hops. There is no membership bitmap, extra seed, disconnected-component recovery, or fallback scan. @@ -46,4 +48,4 @@ unquantized, single-value FLOAT32 RAM HNSW. `test_navix` covers rejected seeds/branches, shared second-hop nodes, equal-distance batch continuation, strategy selection, timeout/reset, frontend filtering/reset, cached -NO/MAYBE decisions, reset invalidation, and isolation between query iterators. +NO/MAYBE decisions, reset invalidation, isolation between query iterators, and backend growth. diff --git a/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h b/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h index 5e88cb230..fcbef823c 100644 --- a/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h +++ b/src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h @@ -110,9 +110,9 @@ template bool HNSW_BatchIterator::navixMayMatch(idType id) { if (index->isMarkedDeleted(id)) return false; - // The NaviX contract keeps internal IDs and the filter stable until reset. - if (navix_filter_cache.empty()) - navix_filter_cache.resize(index->indexSize(), NavixMatch::Unknown); + // Grow from the encountered ID: tiered migration can change indexSize concurrently. + if (id >= navix_filter_cache.size()) + navix_filter_cache.resize(size_t(id) + 1, NavixMatch::Unknown); auto &cached = navix_filter_cache[id]; if (cached != NavixMatch::Unknown) return cached == NavixMatch::Maybe; diff --git a/tests/unit/test_navix.cpp b/tests/unit/test_navix.cpp index 7622c7024..9788022e7 100644 --- a/tests/unit/test_navix.cpp +++ b/tests/unit/test_navix.cpp @@ -130,8 +130,6 @@ TEST(Navix, CachesBothDecisionsAcrossBatchesAndInvalidatesOnReset) { EXPECT_EQ(f.stats.filterRejected, 3u); VecSimBatchIterator_Reset(it); - f.allowed.erase(labelBase + f.node(3)); - f.accept(1); EXPECT_EQ(f.drain(it), f.allowed); for (const auto &[label, calls] : f.filter_calls) EXPECT_EQ(calls, 2u) << label; @@ -155,6 +153,37 @@ TEST(Navix, FilterCacheIsLocalToEachIterator) { VecSimBatchIterator_Free(second); } +TEST(Navix, FilterCacheGrowsForNewBackendNodes) { + Fixture f; + f.sparseGraph(); + const auto new_id = f.graph->indexSize(); + f.allowed.insert(labelBase + new_id); + auto *it = f.iterator(); + auto *reply = VecSimBatchIterator_Next(it, 1, BY_ID); + ASSERT_EQ(reply->results.size(), 1u); + const auto first_label = reply->results[0].id; + VecSimQueryReply_Free(reply); + + const auto capacity = f.graph->indexCapacity(); + VecSimIndex_AddVector(f.index, &f.query, labelBase + new_id); + EXPECT_EQ(f.graph->indexCapacity(), capacity); + // Simulate an appended migration becoming reachable from the saved frontier. + for (idType id = 0; id < f.graph->indexSize(); ++id) + f.graph->getElementLevelData(id, 0).numLinks = 0; + for (auto label : f.allowed) { + if (label == first_label || label == labelBase + new_id) + continue; + auto &links = f.graph->getElementLevelData(label - labelBase, 0); + links.links[0] = new_id; + links.numLinks = 1; + } + auto expected = f.allowed; + expected.erase(first_label); + EXPECT_EQ(f.drain(it), expected); + EXPECT_EQ(f.filter_calls[labelBase + new_id], 1u); + VecSimBatchIterator_Free(it); +} + TEST(Navix, TimeoutInsideSecondHopThenReset) { Fixture f; f.sparseGraph();