Filtering Search Results with Metadata

The Limits of Pure Similarity

Imagine a corporate knowledge base containing documents from HR, Engineering, and Finance. A user asks, "What is our policy on remote work?" A pure similarity search might return:

• The current, active remote work policy (Correct!).
• An outdated draft of the policy from three years ago.
• A blog post from the engineering team discussing their remote work tooling.
• A financial report mentioning costs associated with remote work stipends.

While all of these are semantically related to "remote work," only the first one is the correct answer. The others are noise. Metadata is the tool we use to cut through this noise.

In a vector database, each vector embedding can be stored alongside a structured "payload" of metadata. This is analogous to having columns in a traditional database table that describe a record.

By filtering on this metadata, we can add logical constraints to our semantic search.

Pre-filtering vs. Post-filtering: An Engineering Trade-off

From a system design perspective, there are two primary ways to combine metadata filtering with vector search. Understanding this trade-off is key to building efficient systems.

1. Pre-filtering (Filter-Then-Search): The database first selects all the vectors that match the metadata filter. Then, it performs the similarity search only within this smaller, pre-filtered set of candidates.
2. Post-filtering (Search-Then-Filter): The database first performs the similarity search across the entire collection to find the top N most similar vectors. Then, it filters this small result set to remove any that don't match the metadata criteria.

The diagram below illustrates the pre-filtering approach, which is common in modern vector databases.

The choice between these strategies involves a classic engineering trade-off between speed and accuracy.

• Pre-filtering is highly efficient when your filter is very selective (e.g., tenant_id = 'user_123'), because the vector search is performed on a much smaller number of items. However, it risks missing a globally perfect semantic match if that match was excluded by the initial filter.
• Post-filtering guarantees that you are considering the absolute most semantically similar vectors, but it can be slow (as you search all data) and may return fewer results than you asked for if the top results are filtered out.

For our purposes with ChromaDB, it handles these mechanics internally. We just need to know how to specify the filter.

Applying Filters in ChromaDB

In the previous lesson, you used collection.query() to perform a similarity search. To add a filter, you simply include the where parameter.

ChromaDB uses a filter syntax that is heavily inspired by MongoDB. If you've worked with NoSQL databases, this may look familiar. You construct a dictionary that specifies the conditions your documents' metadata must meet.

# A simple equality filter
# Returns only documents where the metadata 'source' is 'document_A.pdf'
results = collection.query(
    query_texts=["What is the main topic?"],
    n_results=5,
    where={"source": "document_A.pdf"}
)

The article from CodeSignal Learn provides a concise walkthrough of how to build this where clause.

Building Complex Filters

Real-world applications often require more than a single condition. You can build complex filters by combining operators. LINK has a comprehensive table of these operators. For ChromaDB, the most common are:

You can also combine these conditions using logical operators $and and $or. This allows you to express complex business rules directly in your query.

# Find active documents that are either public HR policies OR internal engineering guides.
complex_filter = {
    "$and": [
        {"status": {"$eq": "active"}},
        {"$or": [
            { "$and": [
                {"document_type": {"$eq": "policy"}},
                {"department": {"$eq": "HR"}}
            ]},
            { "$and": [
                {"document_type": {"$eq": "guide"}},
                {"department": {"$eq": "Engineering"}}
            ]}
        ]}
    ]
}

results = collection.query(
    query_texts=["How do I get a promotion?"],
    n_results=3,
    where=complex_filter
)

This ability to nest conditions is powerful and is a pattern you'll be familiar with from writing complex SQL queries or API logic.

Use Case: Self-Querying Retrieval

So far, we've assumed that we, the developers, are manually constructing these filter dictionaries. But what if we could use a large language model to do it for us? This is the core idea behind Self-Querying Retrieval.

In this advanced pattern, a user's natural language query (e.g., "I'm looking for a fruity wine from Italy that's rated above 95") is first sent to an LLM. The LLM's task is to parse this query and generate both:

1. A structured metadata filter: {"country": "Italy", "rating": {"$gt": 95}}
2. The semantic search query: "fruity wine"

The vector store then executes this combined query. This approach elegantly merges the power of semantic search for ambiguous concepts ("fruity") with the precision of structured filtering for factual data (country, rating).

The following video provides an excellent demonstration of this concept.

Conclusion

In this lesson, you've added a critical tool to your RAG toolkit. By moving from simple similarity search to precise, filtered retrieval, you can build applications that are more accurate, efficient, and robust.

Here are the main takeaways:

• From Related to Relevant: Metadata filtering is the key to narrowing search from semantically similar documents to contextually correct ones.
• Filter-then-Search: Modern vector stores typically use a pre-filtering strategy to efficiently search within a subset of data that matches your criteria.
• ChromaDB's where Clause: You can apply filters in ChromaDB by passing a dictionary of conditions to the where parameter in the query() method.
• Complex Logic: You can combine multiple conditions using operators like $eq, $in, $gte, and logical combiners like $and and $or to express sophisticated business rules.
• Advanced Applications: This technique is the foundation for powerful patterns like multi-tenancy, access control, and self-querying retrieval.

We have now covered how to populate a vector store, how to perform similarity search, and how to refine that search with filters. But how do vector stores perform these searches over millions or billions of vectors in milliseconds? A brute-force comparison is computationally infeasible.

In our next and final lesson of this module, we will explore the answer by describing the purpose of Approximate Nearest Neighbor (ANN) search algorithms—the "magic" that makes vector search fast and scalable.