Metadata Filtering

Metadata filtering isn't just about correctness — it's one of the most effective ways to make retrieval both more relevant and faster. By constraining a vector search to records that match structured conditions, you cut noise and shrink the search space. But how you apply the filter — before, during, or after the search — has a big effect on accuracy and speed.

💡 In one line: Filtering restricts retrieval to records matching metadata conditions — and applying it the right way improves both relevance and performance.

Filtering as an Optimization

You already know filtering restricts results to records matching conditions (category, date, tenant, permissions). As a retrieval optimization, it does three things:

  • Improves relevance — removes off-topic hits before they reach the user.
  • Enforces access control — only returns records a user is allowed to see.
  • Speeds things up — a smaller candidate set means less work.

Pre-filter vs. Post-filter vs. Filtered ANN

There are three ways to combine a filter with vector search:

  • Pre-filter — apply the filter first, then search only the matching subset. Accurate, and efficient if the subset is indexed.
  • Post-filter — search first (top-k), then drop non-matching results. Fast, but can return fewer than k if many top hits fail the filter.
  • Filtered ANN (single-stage) — apply the filter during index traversal (payload-aware HNSW). Often the best of both, used by modern databases.

Whiteboard
Whiteboard diagram



The Filtered-ANN Challenge

Aggressive filters can hurt ANN recall: the index graph may route through nodes that get filtered out, missing valid neighbours. Common fixes:

  • Index the metadata (payload indexing) so filters are cheap.
  • Filterable HNSW — traverse only nodes that pass the filter.
  • Over-fetch — retrieve more than k, then filter down.
  • Exact search for very small matching subsets.

Filter Selectivity

The best strategy depends on how selective the filter is:

  • High selectivity (few matches) → pre-filter or exact search is efficient.
  • Low selectivity (most match) → filtered ANN or post-filter is fine.

Whiteboard
Whiteboard diagram


Index Your Filter Fields

Filtering is only fast if the metadata fields are indexed. An unindexed filter forces a full scan of the payloads. Index the fields you filter on — category, tenant, date, status — just as you would in a traditional database.

Combining Conditions

Real filters combine conditions: AND / OR, ranges (date > X), IN lists, and negation. Keep filters simple and selective — overly complex conditions slow things down and are harder to reason about.

Best Practices

  • Index the fields you filter on.
  • Prefer pre-filter or filtered ANN when your database supports it.
  • Watch post-filter returning too few results — over-fetch to compensate.
  • Use filters for access control and multi-tenancy (security, not just relevance).
  • Combine with top-k and reranking (later in this topic).

Code Example


 
Summary
 
     
  • Metadata filtering boosts relevance, security, and often speed.
    •  
  • Pre-filter (accurate), post-filter (fast, may under-return), and filtered ANN (best of both) are the three strategies.
    •  
  • Aggressive filters can hurt ANN recall — use payload indexing, filterable HNSW, or over-fetch.
    •  
  • Match the strategy to filter selectivity, and always index your filter fields.
    •  
  • Filtering pairs naturally with top-k and reranking for optimised retrieval. EOF echo created