Metadata Filtering
Searching the right shelf, not the store
Real searches are scoped: 'in this repo', 'only faq'. Metadata filters narrow the ANN walk first, not after. Getting filter-aware search right beats post-filtering for speed and correctness.
What you will learn
- Index documents with scoping metadata
- Distinguish pre- vs post-filtering
- Avoid filter-relation surprises
What is this?
Metadata attaches business facts (tenant, type, date, tags) to each vector. Filtered search either pre-filters candidates before ANN (or inside the graph walk) or post-filters the result list. Pre-filtering keeps speed but changes the neighborhood; post-filtering risks empty-top-k and scans. Choosing the right pattern per store changes both latency and correctness.
Why do you need it?
- Scoped corpora (per tenant/docset) make unbounded global search both wrong and slow.
- Pre-filtering can shrink neighborhoods so badly that recall collapses — know your store's semantics.
- Post-filtering on small k often returns nothing when the filter is selective.
- Consistency: the filter must apply identically on ingest and query metadata.
Mental model
Searching a department store, aisle-warning
Metadata filtering
Filtering 'shoes only' before you walk (pre-filter) finds the right aisle fast — unless the aisle is so narrow the search has nowhere to roam. Filtering after wandering the whole store (post-filter) wastes trips and forces you to check suspiciously empty hands.
How it works
- Attach metadata (strings/ints/booleans) to each vector at upsert.
- Query includes the filter expression (tenant = X AND type = faq).
- Store integrates filters into the ANN plan (pre-filter / graph-aware).
- Some stores post-filter after top-k — expect degraded behavior on selective filters.
- Cardinality: pre-filtering needs metadata-aware index internals or separate per-tenant indexes.
Pre- vs post-filtering paths.
In production
- Multi-tenant apps pre-filter on tenant id exclusively — data isolation at the index.
- Support desks scope to the customer's tickets, not the whole corpus.
- Freshness filters ('updated < 30 days') blend with vector ordering.
Best practices
- Bake tenant/docscope into the filter AND the ingest-side metadata consistently.
- Understand your store's filter mode (pre-filter vs post-filter) per docs.
- Benchmark the filtered path: selective filters can tank recall if post-filtered.
- Index high-selectivity fields; test filter-bearing query plans.
Common mistakes
- Post-filtering a top-k=5 global search for a rare tenant — returns empty.
- Metadata only on some chunks (asymmetric ingest).
- Assuming filtering happens before the ANN walk when the store post-filters.
Common issues
Filtered results look like global resultsFilter not applied or not honored by index
Verify query filter field names/types; verify store version supports it.
Slow filtered queriesPost-filtering on huge global k
Move to pre-filtering or per-tenant collections/indexes.
Debugging tips
- Selective filters return few results → confirm pre-filter vs post-filter semantics.
- Different tenants, same scores → your filter silently ignored; inspect query object.
- Index scan taint — filtering column NULL on some rows → standardize ingest.
Interview checkpoint
Hands-on lab
- Attach metadata to documents in the index
- Pre-filter candidates before any distance math
- Count what a missing metadata policy would return
Filter Before You Score
25 min · beginner
Quick quiz
Post-filtering danger is chiefly…
Metadata must match between ingest and query; otherwise filters silently misbehave.