Metadata Filtering
Vector databases search by semantic meaning, but sometimes you just want exact constraints (like 'only documents from 2024'). Metadata filtering combines the fuzziness of AI search with the precision of SQL.
Why Does This Exist?
You ask for Q3 2024 sales. Your question goes out as an embedding, the store ranks everything by meaning, and the Q3 2023 report lands on top because it uses almost the same words. You will get a confident answer with last year's number.
Metadata filtering fixes that by attaching exact tags to each chunk and enforcing them before ranking. Meaning still decides, but only among chunks that already satisfy the facts.
This page covers that exact-tag step. Meaning ranking itself lives in semantic search, the store that runs both lives in vector databases, and combining word match with meaning match lives in hybrid search.
The one idea you need first: an embedding turns text into a list of numbers, and similarity is a score from 0 to 1 for how closely two lists point. High means same topic, not same facts. A 2023 report can score 0.91 against your 2024 question while the right chunk scores 0.84. Without tags, 0.91 wins.
Think of It Like This
A record shop with year stickers
You hum a tune and want only 2024 pressings in soul or jazz. A good clerk does not listen to every record in the shop. She first pulls only the crates stickered 2024 plus soul or jazz, then matches your hum inside those crates. The sticker step is exact. The listening step is fuzzy. That order is the whole trick.
It stops here: record stickers are printed where you can see them. Document tags are invisible, and they are only as good as your ingest. A missing year or a wrong department sends the right chunk to the drop pile before ranking starts, and no similarity score can rescue it.
How It Actually Works
At ingest you store two things per chunk: the vector and a small tag set like year, quarter, department, and clearance. At query time you send two things as well: the query vector and a filter object. The store applies the filter first, ranks the survivors by similarity, and returns the top few. Index the fields you filter on, or the filter step scans everything.
The filter rule
In plain words: is your question as numbers, is one stored chunk, is that chunk's tag set, is the filter predicate (a true or false test on the tags), is the similarity score from 0 to 1, and is how many chunks you keep.
A common predicate is a conjunction with a set test:
The kept set is every chunk in the corpus where is true. Those survivors are sorted by , and the top go into the prompt. That is RAG architecture with one extra gate before the rank step.
Pre-filtering beats post-filtering
Pre-filtering applies first, then takes the top of the survivors. Post-filtering takes the top of everything, then throws away the ones that fail . The second order fails whenever the best meaning matches are the wrong facts.
Take . If the two highest similarity scores both fail the filter, post-filtering returns nothing, even when perfect matches sit at rank 3 and 4. Never filter after top-k. Ask the store for single-stage or pre-filtered search.
Worked example: six chunks, three survivors
Your query is Q3 sales totals with the predicate above and :
- D1: year 2023, sales, . Drops. Wrong year, highest meaning score.
- D2: year 2024, sales, . Keeps. Rank 1 of the survivors.
- D3: year 2024, finance, . Keeps. Rank 2 of the survivors.
- D4: year 2024, hr, . Drops. Wrong department, even though it outscores D2 and D3.
- D5: year 2022, sales, . Drops. Wrong year.
- D6: year 2024, sales, . Keeps. Rank 3 of the survivors.
Three of six survive the filter. Ranked by similarity they order D2, D3, D6, so the top 2 are D2 and D3. Without the filter the top 2 would be D1 and D4, and both are wrong for this question. Post-filtering that unfiltered top 2 against the predicate returns an empty list, which is exactly how teams lose a good chunk that sat at rank 3.
The trade-off is strictness for recall. A tighter predicate buys precision but can return nothing, so you will watch the survivor count, not just the final answer. Do not use exact filtering when the constraint is vague, like recent or about money. That is a ranking judgment, and reranking or query rewriting fits better. The method assumes tags are correct and complete at ingest. When they are stale or missing, the filter drops truth before the model ever sees it.
Code
This snippet runs the same six-chunk example with only the standard library, so you can see the filter-then-rank order produce D2 and D3:
from dataclasses import dataclass
@dataclassclass Chunk: id: str year: int dept: str sim: float
def passes(c: Chunk) -> bool: return c.year == 2024 and c.dept in ("sales", "finance")
corpus: list[Chunk] = [ Chunk("D1", 2023, "sales", 0.91), Chunk("D2", 2024, "sales", 0.84), Chunk("D3", 2024, "finance", 0.81), Chunk("D4", 2024, "hr", 0.88), Chunk("D5", 2022, "sales", 0.79), Chunk("D6", 2024, "sales", 0.77),]
kept: list[Chunk] = [c for c in corpus if passes(c)]ranked: list[Chunk] = sorted(kept, key=lambda c: c.sim, reverse=True)unfiltered_top2: list[Chunk] = sorted(corpus, key=lambda c: c.sim, reverse=True)[:2]
print([c.id for c in kept]) # -> ['D2', 'D3', 'D6']print([c.id for c in ranked[:2]]) # -> ['D2', 'D3']print([c.id for c in unfiltered_top2]) # -> ['D1', 'D4']print([c.id for c in unfiltered_top2 if passes(c)]) # -> []Pre-filtering keeps D2, D3, D6 and returns D2 and D3. The unfiltered top 2 are D1 and D4, and filtering them after the fact leaves nothing.
Watch Out For
Your filter returns nothing and you blame the model
The symptom is an empty retrieval or a vague fallback answer on questions you know have docs. The cause is usually a predicate that is too tight: a wrong year, a misspelled department, or an AND of three fields where one tag is missing at ingest.
Log the survivor count before ranking on every query. If it is zero, widen one field at a time and inspect which clause drops everything. Ship a fallback that relaxes the filter or asks for a missing field instead of letting the model guess from nothing.
Filtering after top-k drops the chunk sitting at rank 3
The symptom is flaky retrieval: the right 2024 chunk exists, it scores 0.84, yet some queries return empty while others return last year's report. The store took the top by meaning first, then applied tags, so D1 and D4 filled both slots and the filter emptied them.
Use pre-filtering or single-stage filtered search in the store. If your store only post-filters, overfetch a much larger before filtering, then cut back down. Better still, move to an index that applies the predicate during the search.
The Quick Version
- Metadata filtering enforces exact tags before similarity ranks, so meaning decides only among chunks that satisfy the facts.
- The predicate is a true or false test on tags, like year equals 2024 and department is sales or finance.
- In the six-chunk example the filter keeps D2, D3, D6 and returns D2 and D3, while unfiltered search returns D1 and D4.
- Post-filtering an unfiltered top-k can return nothing when the best meaning matches fail the tags.
- Tight filters trade precision for empty results, so log the survivor count and relax the predicate before you blame the model.