recallA retrieval
field guide

Filtered Vector Search

Build this skill

Filter vector search by metadata correctly, avoiding the empty results of naive post-filtering.

Search only where the answer can be

A first-year student opens the hostel page of the college portal and asks, "what is the fee?". A plain vector search over the whole knowledge base might return the re-evaluation fee, last year's hostel fee, and a staff training fee. All three are "about fees", so their embeddings are close to the question, and none of them should have been considered.

Filtered vector search combines similarity search with ordinary conditions on metadata: "find the closest chunks where the status is current, the access level includes students, and the collection is hostel". Filters remove off-topic material, enforce permissions, and handle time ("this year's fees"), which an embedding has almost no sense of.

Pre-filtering and post-filtering

A filter can be applied at two points, and the choice changes the results.

Post-filtering searches first and filters afterwards: find the top K closest chunks, then throw away those that fail the filter. It is simple, but if most of the top K fail, you are left with fewer than K results, or none, even though chunks that pass exist further down the ranking.

Pre-filtering applies the filter first and searches only among the chunks that pass. It returns up to K valid results every time, but it can be slow if the index was not designed for filtering.

Picture choosing a cricket team of first-years. Post-filtering picks the best eleven players in the college and then removes everyone who is not a first-year. If the best eleven are all seniors, there is no team. Pre-filtering looks only at first-years and picks the best eleven of them.

Post-filtering1. Find top 5 of all chunks2. Remove those failing the filterFast and simpleMay return 0–4 resultsMisses good matches ranked 6+Pre-filtering1. Keep only chunks passing the filter2. Find top 5 among themAlways up to 5 valid resultsNeeds filter-aware indexesCan be slower if done naively

Post-filtering can silently return too few results. Pre-filtering returns the best valid results.

Try both orders on nine chunks ranked for a student's question. Most of the closest ones are staff documents.

The same problem in code

The program below reproduces the situation. results is the full ranking for one question, and the student may only see chunks whose access level is students.

python · runs in your browser

Expected output:

text
post-filtering:         []
pre-filtering:          ['Student medical leave rules', 'Student leave certificate rule']
post-filter, fetch 4xK: ['Student medical leave rules', 'Student leave certificate rule']

The post line cuts the list to the top 5 first and only then checks access. All five are staff documents, so nothing survives, although two good student documents sat just below the cut. No error is raised; the system simply answers "I could not find anything", which makes this a hard bug to notice. The pre line checks access across the whole list and then takes up to 5.

The third line is a common repair called over-fetching: retrieve 4 × K candidates, filter them, and keep the best K. It rescues this case, but if a filter passes only one chunk in a thousand, even 20 candidates will usually contain none.

How databases handle it

In pgvector, a filter is simply a WHERE clause.

sql
SELECT d.title, c.content
FROM chunks c JOIN documents d USING (doc_id)
WHERE d.access = 'students'
  AND d.status = 'current'
  AND d.collection = 'hostel'
  AND c.metadata->>'year' = '2026'          -- a field inside a JSONB column
ORDER BY c.embedding <=> :q
LIMIT 5;

The WHERE lines are the filter and ORDER BY ... LIMIT 5 is the vector search; PostgreSQL decides how to combine them. With an HNSW index and a very selective filter, older pgvector versions could return fewer than K rows, which is the post-filtering effect. Newer versions added iterative index scans, which keep walking the index until enough rows pass. For a filter used on nearly every query, a partial index, built only over the rows matching a condition, is another option.

Purpose-built vector databases such as Qdrant, Milvus and Weaviate build filter-aware indexes, which check the metadata conditions during the graph search itself.

Common filters in practice

Filter Example Why
Access access IN user_roles Permissions: never show what a user may not see
Status / version status = 'current' Hide superseded rules
Collection or department collection = 'hostel' Search where the answer can be
Date effective_from <= today Questions about current rules or a given year
Document type doc_type = 'form' "Where is the form for…" questions
Language language = 'hi' Prefer documents in the user's language

Access and status filters protect people and correctness, so the system should attach them to every query itself. The others are helpers whose values can come from where the user is in the app, as with the hostel page, or be picked out of the question.

Follow your curiosity.

↑ ↓ to explore · Enter to open · Escape to close