Vector Search Filtering: Combining Semantic Similarity with Metadata Constraints

The Filtering Problem

Pure vector search answers: "What are the most semantically similar items to my query?" But real applications need more. A customer support bot should only return articles for the customer's product. A legal search engine should filter by jurisdiction and date. A multi-tenant RAG system must restrict results to the current user's documents.

Combining semantic similarity with metadata constraints is one of the most important — and most misunderstood — aspects of vector database design. Get it right and you have fast, accurate, scoped search. Get it wrong and you have either slow queries or missing results.

Pre-Filtering vs Post-Filtering

There are two fundamental approaches to filtered vector search:

flowchart LR
    Q(["User query"])
    EMB["Embed query<br/>text-embedding-3"]
    VEC[("Vector DB<br/>pgvector or Pinecone")]
    RET["Top-k retrieval<br/>k = 8"]
    PROMPT["Augmented prompt<br/>system plus context"]
    LLM["LLM generation<br/>Claude or GPT"]
    CITE["Inline citations<br/>and page anchors"]
    OUT(["Grounded answer"])
    Q --> EMB --> VEC --> RET --> PROMPT --> LLM --> CITE --> OUT
    style EMB fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style VEC fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style LLM fill:#4f46e5,stroke:#4338ca,color:#fff
    style OUT fill:#059669,stroke:#047857,color:#fff

Pre-filtering applies metadata constraints first, then runs vector search only on the matching subset. The result set always satisfies both the filter and the similarity criteria.

Post-filtering runs vector search on the full dataset first, then removes results that do not match the metadata filter. This can return fewer results than requested if many top-similarity items fail the filter.

# Conceptual difference (pseudocode)

# Pre-filter: narrow first, then search
candidates = filter_by_metadata(all_vectors, category="legal")
results = vector_search(candidates, query, k=10)
# Always returns 10 results (if 10+ candidates exist)

# Post-filter: search first, then narrow
results = vector_search(all_vectors, query, k=100)
results = [r for r in results if r.category == "legal"][:10]
# Might return fewer than 10 if few legal docs are in top 100

Most modern vector databases use pre-filtering because it guarantees the requested number of results. However, the implementation details matter enormously for performance.

Filtering in Pinecone

Pinecone applies filters before the ANN search. Design your metadata schema with queryable fields:

from pinecone import Pinecone

pc = Pinecone(api_key="your-key")
index = pc.Index("documents")

# Upsert with rich metadata
index.upsert(vectors=[{
    "id": "doc-1",
    "values": embedding,
    "metadata": {
        "tenant_id": "acme-corp",
        "category": "legal",
        "date": "2026-01-15",
        "language": "en",
        "confidential": False
    }
}])

# Query with compound filter
results = index.query(
    vector=query_embedding,
    top_k=10,
    filter={
        "$and": [
            {"tenant_id": {"$eq": "acme-corp"}},
            {"category": {"$in": ["legal", "compliance"]}},
            {"date": {"$gte": "2025-01-01"}},
            {"confidential": {"$eq": False}}
        ]
    },
    include_metadata=True
)

Filtering in pgvector

pgvector leverages PostgreSQL's native WHERE clauses. This is one of pgvector's biggest advantages — you can use the full power of SQL alongside vector search:

-- Combined vector search with relational filters
SELECT d.id, d.title, d.embedding <=> query_vec AS distance
FROM documents d
JOIN categories c ON d.category_id = c.id
WHERE c.name IN ('legal', 'compliance')
  AND d.tenant_id = 'acme-corp'
  AND d.created_at >= '2025-01-01'
  AND d.is_confidential = false
ORDER BY d.embedding <=> query_vec
LIMIT 10;

With pgvector, you get JOINs across tables, subqueries, CTEs, and every SQL feature. The query planner decides whether to use the vector index, a B-tree index on metadata columns, or a combination.

# Python with psycopg
def filtered_search(
    query_vec: list[float],
    tenant_id: str,
    categories: list[str],
    limit: int = 10
) -> list[dict]:
    return conn.execute("""
        SELECT id, title, embedding <=> %s::vector AS distance
        FROM documents
        WHERE tenant_id = %s
          AND category = ANY(%s)
        ORDER BY embedding <=> %s::vector
        LIMIT %s
    """, (query_vec, tenant_id, categories, query_vec, limit)).fetchall()

Filtering in Chroma

Chroma supports where (metadata filter) and where_document (text content filter):

results = collection.query(
    query_texts=["contract termination clause"],
    n_results=10,
    where={
        "$and": [
            {"tenant_id": {"$eq": "acme-corp"}},
            {"category": {"$eq": "legal"}}
        ]
    },
    where_document={"$contains": "termination"}
)

Performance Optimization Strategies

1. Index your filter columns. In pgvector, create B-tree indexes on columns you frequently filter by. In Pinecone, high-cardinality metadata fields benefit from being stored as metadata rather than in namespaces.

-- pgvector: compound index for common filter patterns
CREATE INDEX idx_docs_tenant_category
ON documents (tenant_id, category);

2. Use namespaces for the primary partition. If every query filters by tenant, use namespaces (Pinecone) or partitions (pgvector) instead of metadata filters:

# Pinecone: namespace-based isolation is faster than metadata filtering
index.upsert(vectors=[...], namespace="acme-corp")
results = index.query(vector=qvec, top_k=10, namespace="acme-corp")

3. Avoid high-cardinality filters on non-indexed fields. Filtering by a unique user ID across millions of vectors is expensive if the field is not indexed. Structure your data so that common filters align with the database's partitioning strategy.

4. Profile your queries. In pgvector, use EXPLAIN ANALYZE to see whether the query planner uses the vector index, the metadata index, or a sequential scan:

EXPLAIN ANALYZE
SELECT id, embedding <=> '[...]'::vector AS distance
FROM documents
WHERE tenant_id = 'acme-corp'
ORDER BY embedding <=> '[...]'::vector
LIMIT 10;

Query Design Patterns

Tiered filtering: Apply the most restrictive filter first to reduce the candidate set before vector search:

# If tenant has 1000 docs out of 10M, filter by tenant first
results = filtered_search(query_vec, tenant_id="small-tenant", limit=10)

Fallback broadening: If a strict filter returns too few results, broaden the filter and re-query:

def search_with_fallback(query_vec, filters, limit=10):
    results = filtered_search(query_vec, **filters, limit=limit)
    if len(results) < limit:
        # Broaden: remove date filter
        broader_filters = {k: v for k, v in filters.items() if k != "date"}
        results = filtered_search(query_vec, **broader_filters, limit=limit)
    return results

FAQ

Will metadata filtering slow down my vector queries significantly?

It depends on the selectivity of the filter and whether the filter fields are indexed. If a filter reduces the candidate set from 10 million to 1,000 vectors, the vector search runs much faster because it searches fewer candidates. If the filter is unselective (matches 90% of vectors), the overhead is minimal. The worst case is high-cardinality filters on non-indexed fields, which can cause full scans.

Should I store text content in the vector database metadata or in a separate database?

Store only the fields you need for filtering and display in vector database metadata. Keep full document content in your primary database (PostgreSQL, MongoDB, etc.) and look it up by ID after retrieval. This keeps vector database storage costs down and avoids metadata size limits that some databases impose.

How do I handle date range filtering in vector databases that only support equality operators?

Pinecone and most vector databases support comparison operators ($gte, $lte) on numeric and string fields. Store dates as ISO strings (YYYY-MM-DD) which sort lexicographically, or as Unix timestamps (integers). Both approaches work with range filters across all major vector databases.

---

#VectorSearch #MetadataFiltering #QueryDesign #Performance #RAG #AgenticAI #LearnAI #AIEngineering