The Core Idea: Similarity search knows what a chunk is about, but it does not know whether the chunk is current, which department wrote it, or whether the person asking is allowed to read it. Metadata filtering adds those rules. It is how a RAG system returns only the 2025 policy instead of the 2023 one, only HR documents for an HR question, and only what a user has permission to see.
1. Beginner: Why Similarity Alone Is Not Enough
Imagine asking a librarian for the vacation policy. Without any rules they might hand you the 2023 policy, a finance document that merely mentions vacation, and a confidential file that belongs to someone else, all because the words match. The content is similar, yet the results are wrong for you.
Time
Old versions of a document score as high as the new one. Users need the current answer.
Scope
A chunk can be about the right topic but belong to the wrong team, product or region.
Permission
Some chunks must never be shown to some users, however relevant they are.
2. Beginner: Kinds of Metadata Filters
A filter is a condition on a metadata field that a chunk must satisfy to be returned. The fields come from the metadata you stored during ingestion, which is why that lesson matters.
| Filter type | Example | Typical use |
|---|---|---|
| Equality | department equals hr | Scope by team or product |
| Range | year at least 2025 | Dates and freshness |
| Set membership | region in the list EU, UK | Regions and languages |
| Status | status equals active | Hide superseded versions |
| User or tenant | tenant equals the caller | Multi-customer isolation |
| Combinations | AND, OR and NOT of the above | Real queries, which need several rules at once |
3. Intermediate: Pre-Filtering vs Post-Filtering
The order of filtering and searching matters a great deal.
Post-filtering
Search first, take the top k, then remove results that fail the filter. Easy to build, but the top k may be full of disallowed chunks, leaving few or no results.
Pre-filtering
Restrict the search to allowed chunks, then rank them and take the top k. You get k valid results, but the index must support it efficiently.
Many vector databases support filtered search natively, applying the conditions while they walk the index. This gives the benefit of pre-filtering without scanning everything. Whenever you evaluate a database, test what happens when a filter is very strict, because performance and recall can both change.
Rule of thumb: use pre-filtering, or native filtered search, for any rule that must hold. Use post-filtering only for soft preferences where getting fewer results is acceptable.
4. Intermediate: Multiple Filters and Retrieval Constraints
Real questions combine rules. Treat each rule as either a hard constraint that must hold, or a soft preference that only adjusts the score.
| Kind | Behavior | Example |
|---|---|---|
| Hard constraint | Chunks that fail are removed | Status active, user has access |
| Soft preference | Chunks that match get a score boost | More recent documents rank slightly higher |
Filters can also come from the question itself. A request such as last year HR policy contains a department and a date. A language model or simple rules can extract these into filter fields, a technique often called self-querying. It is powerful but risky: a wrong guess silently hides the correct answer. Log extracted filters, and fall back to an unfiltered search when the filtered one returns nothing.
5. Advanced: Access Control Done Safely
Permission filters protect confidential data, so they need stricter handling than other filters.
Enforce on the server. Apply the permission filter in your retrieval code, using the verified identity of the caller. Never rely on asking the model to ignore chunks it should not mention.
Filter before the prompt. A forbidden chunk that reaches the prompt can leak, because the model may quote it.
Isolate tenants. Use a mandatory tenant field on every record, and make the filter impossible to skip.
Test adversarially. Write tests where a user asks directly for content they must not see, and check that nothing comes back.
Keep metadata correct. A wrong or missing label is a silent leak or a silent miss, so validate metadata at ingestion.
Remember: when the filtered result is empty, say so honestly. Do not widen the filter on your own to find something, because that may violate the rule the filter was enforcing.
6. Visual Explanation: Filter Before You Rank
Panel A compares pre-filtering with post-filtering. Panel B shows the results of the code below. Panel C lists filter design questions.
Panel A · Two OrdersSame data, different results
Post-filter
Search, then filter
Rank all chunks
↓
Keep the top k
↓
Drop chunks that fail the filter
↓
May return fewer than k
Pre-filter
Filter, then search
Keep only allowed chunks
↓
Rank those
↓
Take the top k
↓
Returns k valid chunks
Panel B · Results from the CodeQuery: vacation policy, HR, 2025 or later
| Method | Returned chunks |
|---|---|
| No filter | c1, c2, c3 (old and wrong versions) |
| Post-filter, top 3 | c3 only |
| Pre-filter, top 3 | c3, c7 |
Post-filtering lost two result slots to chunks that were later removed
Panel C · Design QuestionsClick a question to open it
Click to see why strict filters can hurt recall▼
A very restrictive filter leaves a small pool, and some approximate indexes struggle to find neighbors inside it. Always test your database with the strictest realistic filters.
How to read it: Panel A is the key idea, Panel B proves it with numbers, and Panel C helps you make safe filter decisions.
7. Python Implementation: Pre-Filter vs Post-Filter
The program holds seven chunks, each with a department and a year. A simple word-overlap score ranks them. It then runs the same query three ways: with no filter, with the rule applied after taking the top 3 results, and with the rule applied before ranking.
metadata_filtering.pyPython 3.10+ · Standard library only
chunks = [ ("c1", "hr", 2023, "vacation policy: 15 days per year"), ("c2", "hr", 2024, "vacation policy: 18 days per year"), ("c3", "hr", 2025, "vacation policy: 20 days per year"), ("c4", "finance", 2025, "travel policy: book flights two weeks ahead"), ("c5", "finance", 2023, "vacation travel refunds are not covered"), ("c6", "it", 2025, "laptop policy: replace every 3 years"), ("c7", "hr", 2025, "holiday calendar for the year"),] def words(text): return set("".join(ch if ch.isalnum() else " " for ch in text.lower()).split()) def score(query, text): return len(words(query) & words(text)) def search(query, k, allowed=None, filter_first=True): pool = chunks if not filter_first or allowed is None else [c for c in chunks if allowed(c)] ranked = sorted(pool, key=lambda c: (-score(query, c[3]), c[0]))[:k] if not filter_first and allowed is not None: ranked = [c for c in ranked if allowed(c)] return [c[0] for c in ranked] def rule(chunk): return chunk[1] == "hr" and chunk[2] >= 2025 query = "vacation policy"print("Filter: department hr and year 2025 or later")print("Search with no filter :", search(query, 3))print("Post-filter (top 3 first):", search(query, 3, rule, filter_first=False))print("Pre-filter (filter first):", search(query, 3, rule, filter_first=True))Expected output
Filter: department hr and year 2025 or laterSearch with no filter : ['c1', 'c2', 'c3']Post-filter (top 3 first): ['c3']Pre-filter (filter first): ['c3', 'c7']Without a filter, the top three results are the vacation policies from 2023, 2024 and 2025, so the user gets two outdated answers. Post-filtering removes the old ones but leaves only a single result, because the top three slots were already used up. Pre-filtering searches only chunks that pass the rule, so it returns every valid chunk up to the limit. Note that the second pre-filter result scores 0 for this query, so in practice you would pair filtering with a minimum score.
Knowledge Check
Q1. Why can post-filtering return fewer results than requested?
Q2. Where should user permission filters be enforced?
Q3. What is the difference between a hard constraint and a soft preference?
Key Points
✓
Similarity search cannot know about time, scope or permission, so metadata filters add those rules.
✓
Common filters are equality, range, set membership, status, user or tenant, and combinations.
✓
Pre-filtering, or native filtered search, returns k valid results; post-filtering can return too few.
✓
Treat rules as hard constraints or soft preferences, and boost recent documents as a soft rule.
✓
Filters extracted from the question can be wrong, so log them and fall back carefully.
✓
Enforce permissions on the server before chunks reach the prompt, and test with adversarial questions.
✓
Return an honest empty result instead of loosening a filter that protects data.
The Big Picture
Metadata turns a similarity engine into a controlled search system. Relevance decides which chunks are about the question; metadata decides which chunks are allowed, current and in scope. Both are needed for answers people can trust.
Query → Apply hard filters → Rank by similarity → Boost soft preferences → Candidates
Up Next: Reranking and Retrieval Optimization. You will learn why a second, more accurate ranking stage helps, how cross-encoders differ from bi-encoders, and how contextual compression trims retrieved passages.