Filtered Approximate Search and Iterative Scans

In pgvector approximate searches, ordinary filters are commonly applied as candidates are scanned. A selective tenant, category, or date predicate can therefore leave fewer than the requested top-k rows. Increase search effort, enable iterative scans where supported, add relational indexes, or change physical design with partial indexes or partitioning—then measure recall and latency.

What will you be able to do?

• Explain why filtered ANN can return too few rows.
• Use HNSW and IVFFlat iterative scans.
• Choose between B-tree, partial ANN, and partition strategies.
• Test strict versus relaxed result order.
• Tune by filter-selectivity slice.

Why do rows disappear?

If an HNSW scan visits 40 candidates and only 10% pass the filter, roughly four may survive; the exact number depends on data and graph traversal. Raising hnsw.ef_search may help. Current pgvector versions also support iterative scans that continue exploring until enough rows are found or a safety limit is reached.

strict_order preserves exact distance ordering among found candidates. relaxed_order can improve recall/speed but may need materialization and reordering when strict presentation matters. IVFFlat has corresponding iterative-scan and maximum-probe settings. Confirm setting names and defaults for the installed version.

Which physical design should you use?

• Add a B-tree index when the relational filter itself is selective and exact vector search over the remaining rows is affordable.
• Add a partial vector index for a few stable high-value predicates.
• Partition when many disjoint values, lifecycle, or operational isolation justify it.
• Avoid one ANN index per tenant when tenant count is large or volatile.

Partial-index predicates must match query semantics and remain maintainable.

How do you verify it?

Build queries at 90%, 10%, 1%, and 0.1% selectivity. For each, compare exact results with ANN using default, higher effort, strict iterative, and relaxed iterative settings. Record result count, recall@k, latency, buffers, and plan. Include tenants with few rows.

What breaks in production?

• A top-10 API silently returns two rows after adding ANN.
• One tuning value is used for every filter shape.
• Relaxed ordering is presented as exact distance order.
• Thousands of tenant-specific indexes overload maintenance.
• Query predicates do not imply partial-index predicates.

AI pair-work prompt

Analyze this filtered pgvector workload [queries, selectivity histogram, index DDL]. Propose B-tree, search-effort, iterative-scan, partial-index, and partition experiments. Include exact recall, returned-count, latency, and maintenance tradeoffs for every selectivity slice.

Verification contract: No design passes unless it meets minimum returned-count and recall objectives for the rarest authorized slice.

Check your understanding

1. Why can post-scan filtering reduce result count?
2. What tradeoff does relaxed ordering make?
3. When might exact search after a B-tree filter be best?

Official references

• pgvector filtering
• PostgreSQL partial indexes
• PostgreSQL partitioning