DEFERRED (until lifecycle/DDL changes): Route filtered queries by selectivity, and score allowlists exactly (speedkick) - #1602

Purpose of the change

A property filter reached the search engine as a Container[int] — a predicate backed by SQL, issuing one point query per candidate the search touched, memoized within a call. An HNSW traversal touches hundreds to thousands of candidates, so a filtered query paid that many round trips.

It also closed off a capability. A container that only answers in cannot be handed to an engine that has a native allowlist, so no engine could restrict its scan to the allowed set — every one of them had to search unrestricted and discard.

Description

The filter resolves before the search. A LIMIT probe fetches one row past selective_filter_limit — the extra row is what separates "at most this many" from "more than this many":

• Selective (at or under the threshold): the probe already holds every matching row_id, so it goes to the engine as an allowlist. One SQL query for the whole query batch.
• Broad (over it): the search runs unrestricted and survivors are post-filtered with bounded widening — 4× per round up to limit * max_overfetch_factor, then returning what survived rather than widening without end.

allowed_keys: Container[int] becomes allowlist: Collection[int], and hnswlib and usearch answer an allowlist by gathering those vectors and scoring them directly.

That change is about correctness, not only cost. Overfetch-and-post-filter is approximate: allowed vectors the unrestricted search never reaches are simply missed. Gather-and-score reaches every one. hnswlib also stops threading a filter callback through its knn_query fallbacks, and turbovec can now be handed the allowlist its native search already accepts (#1599).

One engine instead of two. _KeyFilter was the only consumer of the store's synchronous SQLAlchemy engine — a second pysqlite engine built from the async URL, with its own connect hook registering the foreign-keys pragma. Both go with it.

Scoring is an inner product now

Scoring a gathered vector by cosine meant dividing by its norm, and that division was most of the work — the row-norm pass is unvectorized where the matmul is BLAS:

np.linalg.norm(m, axis=1)   1.78 ms     # 10_000 x 768
m @ q  (BLAS gemv)          0.28 ms

85% of the time, guarding the 15%. It was also recomputed per query vector, over a matrix gathered once.

Vectors are scaled to unit length on the way in instead — usearch on add, where its scale-invariant metric is indifferent to the change; hnswlib already does it under space="cosine" — and queries at the top of the search, before the allowlist branch. Scoring is then a plain inner product, which for unit vectors is the cosine similarity, and the helpers say so: cosine_similarities → inner_products, unit_vectors is the one place scaling happens, and top_k_matches states the precondition it ranks under.

Q=1:  1.89 ms -> 0.31 ms   (6.1x)
Q=8: 15.50 ms -> 2.59 ms   (6.0x)

Scores are clamped onto [-1, 1]: usearch's f16 storage returns gathered vectors at 0.999–1.0009, which the old division hid and a raw dot does not. That is O(k), not O(N·D).

New knobs

Tests

Neither engine had a single allowlist test, and neither knob was exercised. This adds 21, and no test passed a vector that was not already unit. Eight new ones pin that magnitudes never reach the score, on both the engine's own path and the allowlist path. The other 13: test_allowlist_restricts_results, test_allowlist_excludes_best_match, test_empty_allowlist_returns_nothing and test_missing_allowlist_keys_ignored for hnswlib and usearch, plus five store-level regime tests covering ranking, sparse filters, widening, the widening cap, and that the two regimes agree.

I checked they discriminate rather than trusting a green run. Ablating the engine allowlist path fails exactly five — restricts_results and excludes_best_match on both engines, plus selective_and_broad_agree. The eight survivors are correctly independent of it: the empty-allowlist tests are caught by the guard in search() before _sync_search, the missing-key tests hold one-key indexes, and the broad-path tests set selective_filter_limit=0 to force the store-side post-filter. Ablating the widening loop fails test_broad_path_widens_until_filled alone.

Verification

• pytest packages/server/server_tests: 1919 passed, 3 skipped, 1 failed.
• ty check --project packages/server: clean.
• ruff check / ruff format --check: clean.

The one failure is test_get_version, pre-existing on speedkick: it rejects the .post segment git describe puts into the derived version. Nothing here touches versioning or tags.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NKmF9xNph9QH3ozNw3ZnJL