Skip to content

Apply rowid filters to IVF KNN queries - #350

Open
MayCXC wants to merge 2 commits into
asg017:mainfrom
MayCXC:ivf-rowid-in
Open

MayCXC wants to merge 2 commits into
asg017:mainfrom
MayCXC:ivf-rowid-in

Conversation

@MayCXC

@MayCXC MayCXC commented Oct 23, 2026 •

Copy link
Copy Markdown

A KNN query on an IVF column ignores a rowid in (...) filter and returns the unfiltered k nearest rows.

create virtual table v using vec0(a float[8] indexed by ivf(nlist=4, nprobe=1));
-- 40 inserts, then compute-centroids; :q is row 3's vector
select rowid, distance from v where a match :q and k = 3 and rowid in (1, 2);
-- 3 (0.0), 30 (1.379), 10 (1.4); a flat column returns 1 (2.099), 2 (2.929)

vec0Filter_knn() collects the rowids the filter names, and vec0BestIndex() tells SQLite to omit the constraint, but the IVF dispatch never passed them to ivf_query_knn(). It now does, and a filter's rows are ranked by their exact distances, read through ivf_get_vector_data(), skipping a rowid the table does not have. The cell scan and the oversample re-rank run only without a filter: the probed cells hold the rows near the query, which the filter may not name, so a filter applied to them alone would miss the named rows in other cells (above, row 2 is in a cell that nprobe=1 does not probe).

This builds on #349 and carries its commit, since on main ivf_get_vector_data() returns a quantized column's quantized bytes rather than its vectors.

Test: test_ivf_knn_rowid_in in test-ivf.py compares rowids and distances with a flat column built from the same vectors, before and after compute-centroids, for filters that name rows outside the probed cell and a rowid the table does not have, parametrized over no quantizer, int8 and binary. All three fail on main and on #349 and pass here. The Python suite passes (with -DSQLITE_VEC_EXPERIMENTAL_IVF_ENABLE=1, 306 passed, 4 skipped; without it, 239 passed, 71 skipped), under ASan and UBSan as well, and both builds' warnings are main's.

The distance half is #316, which applies distance constraints in every backend. The two merge cleanly, and together a distance constraint applies to the k rows the filter ranked, as it does to the probed cells' results, so rowid in (...) and distance > x can return fewer than k of the named rows where a flat column returns k. This also merges cleanly with every open PR that touches the IVF code, #313, #343 and #347 included.

Origin. Found in the IVF port to photostructure/sqlite-vec, photostructure#12 (65817f4), whose ivf_knn() takes the rowid filter and distance constraints of the rescore index's KNN; the change and its test are written here for asg017's main. No open or closed PR or issue here makes the same change.

A quantized IVF column keeps each vector's int8 or binary form in its
cell and the vector as it was inserted in _ivf_vectors, but
ivf_get_vector_data() returned the cell's bytes for every column. A
point query then read the column's float32 elements past the end of
the quantized vector, and a full scan or a KNN query returned the
quantized bytes as the column's value. A quantized column's vectors
are now read from _ivf_vectors.
vec0Filter_knn() collects the rowids a KNN query's `rowid in (...)`
constraint names, and xBestIndex tells SQLite to omit the constraint,
but the IVF dispatch never passed them to ivf_query_knn(), so a filtered
query on an IVF column returned the unfiltered k nearest rows.
ivf_query_knn() now takes them and ranks the rows they name by their
exact distances, read through ivf_get_vector_data(), skipping a rowid
the table does not have; the cell scan and the oversample re-rank run
only without a filter.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant