faiss: bound filtered IVF range scans to eligible IDs

[SimBuddy]

Summary

Filtered IVF range search can currently enter a list scanner and visit IDs/codes that a plain sorted ID selector will reject anyway.

This change uses the selector's exact sorted ID bounds before scanner setup:

• intersect the selected inverted list with the selector's eligible ID interval;
• skip scanner setup when the intersection is empty;
• otherwise scan only the eligible IDs and corresponding codes.

The existing path is preserved for unfiltered searches and selector/list configurations where these bounds are not known to be exact.

Why

For sparse filtered range searches, the coarse IVF search may select many physical lists even though only a very small fraction of the IDs in those lists are eligible under the selector.

Previously, those excluded IDs could still reach per-list scanner/code work before the selector removed them.

The selector already provides sufficient information to determine the exact eligible contiguous interval, so that filtering can happen before the expensive inner scan without changing which vectors are valid results.

No new persistent metadata or controller state is introduced.

Scope

The optimized path is limited to the compatible plain sorted ID-selector case.

The original behavior remains unchanged for:

• unfiltered searches;
• custom or context-dependent selectors;
• iterator-backed lists where equivalent bounds are not established;
• pair labels;
• other selector representations that do not provide the required exact sorted interval.

Eligible distance calculations, radius checks, and returned range-search results are unchanged.

Work reduction

On the representative SIFT1M validation workload:

• nprobe=256
• batch size 128
• selector IDs [0, 100)

the original IVFFlat range path presented approximately 32.6 million IDs to list scanners.

With this change, the scanners receive only 4,226 eligible IDs.

Of 32,768 selected physical lists, 29,488 have no eligible intersection and therefore avoid scanner setup entirely.

The useful distance calculations remain the same.

Performance

On the same frozen filtered-range workload, the measured speedups were approximately:

• IVFFlat

  • 1 thread: 15.5x
  • 4 threads: 15.0x
  • 8 threads: 13.8x

• IVFPQ with precomputed tables

  • 1 thread: 12.6x
  • 4 threads: 11.9x
  • 8 threads: 12.6x

• IVFPQ without precomputed tables

  • 1 thread: 11.0x
  • 4 threads: 10.5x
  • 8 threads: 9.5x

These numbers are specific to sparse filtered range search and should not be interpreted as a general Faiss speedup.

Unfiltered and unsupported-selector paths retain the existing implementation.

Correctness

The change preserves the exact eligible ID set and only moves selector-bounding work ahead of scanner/code processing.

Validation covers:

• exact range-result equality;
• empty eligible intersections;
• partial intersections;
• list-boundary cases;
• full intersections;
• multiple inverted lists;
• IVFFlat;
• IVFPQ;
• fallback behavior for unsupported selectors.

Broader exact-output comparisons were also run across the retained implementation.

Method

The opportunities were identified and validated using WOB/WOB3 techniques.

WOB is an experimental method of refocussing workloads in data-heavy code. I am stress testing various codebases, to develop the method further, and faiss seemed like a worthwhile candidate. The results were good, so I am sharing. Feedback would be greatly appreciated.

WOB is human-designed, human-led, and machine assisted.