Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/navix-poc.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +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 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.
Expand All @@ -34,10 +40,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, isolation between query iterators, and backend growth.
17 changes: 14 additions & 3 deletions src/VecSim/algorithms/hnsw/hnsw_batch_iterator.h
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ class HNSW_BatchIterator : public VecSimBatchIterator {
using candidatesMinHeap = vecsim_stl::min_priority_queue<DistType, Identifier>;

VecSimNavixParams navix{};
enum class NavixMatch : uint8_t { Unknown, No, Maybe };
vecsim_stl::vector<NavixMatch> navix_filter_cache;
vecsim_stl::vector<idType> navix_direct, navix_second;
vecsim_stl::vector<uint8_t> navix_matches;
vecsim_stl::vector<std::pair<DistType, idType>> navix_branches;
Expand Down Expand Up @@ -83,9 +85,10 @@ HNSW_BatchIterator<DataType, DistType>::HNSW_BatchIterator(
std::shared_ptr<VecSimAllocator> 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;
Expand All @@ -107,9 +110,16 @@ template <typename DataType, typename DistType>
bool HNSW_BatchIterator<DataType, DistType>::navixMayMatch(idType id) {
if (index->isMarkedDeleted(id))
return false;
// 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;
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;
Expand Down Expand Up @@ -397,6 +407,7 @@ template <typename DataType, typename DistType>
void HNSW_BatchIterator<DataType, DistType>::reset() {
this->resetResultsCount();
this->depleted = false;
navix_filter_cache.clear();

// Reset the visited nodes handler.
this->visited_tag = this->visited_list->getFreshTag();
Expand Down
74 changes: 73 additions & 1 deletion tests/unit/test_navix.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
#include "VecSim/vec_sim.h"
#include "VecSim/algorithms/hnsw/hnsw_single.h"
#include "VecSim/query_result_definitions.h"
#include <map>
#include <set>

namespace {
Expand All @@ -20,6 +21,7 @@ struct Fixture {
HNSWIndex<float, float> *graph;
idType seed;
std::set<size_t> allowed;
std::map<size_t, size_t> filter_calls;
VecSimNavixStats stats{};
VecSimQueryParams params{};
float query = 0;
Expand All @@ -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<Fixture *>(ctx)->allowed.contains(label) ? 1 : 0;
auto *fixture = static_cast<Fixture *>(ctx);
++fixture->filter_calls[label];
return fixture->allowed.contains(label) ? 1 : 0;
},
this, &stats, false};
}
Expand Down Expand Up @@ -112,6 +116,74 @@ 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);
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, 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();
Expand Down
Loading