Metadata Filtering in Vector Search

The Problem#

Semantic similarity does not understand permissions. A vector search query can find the perfect chunk from the wrong tenant, old document version, or restricted workspace unless metadata filtering is built into retrieval.

Why It Matters#

Vector search often powers user-facing RAG. Returning unauthorized context is a security bug, and returning stale or wrong-version context is a correctness bug.

Core Concepts#

Metadata filtering restricts search by fields such as tenant id, user group, document type, version, region, language, or effective date. The hard part is selectivity. A highly selective filter can reduce the candidate pool so much that a global vector index becomes inefficient.

Implementation#

Store authorization and freshness metadata with every chunk:

{
  "documentId": "runbook-123",
  "tenantId": "acme",
  "visibility": "engineering",
  "version": "2026-08",
  "effectiveFrom": "2026-08-01",
  "embedding": [0.012, -0.044]
}

Apply filters as part of retrieval, not after answer generation.

Example#

A user from tenant acme asks:

How do I rotate the production webhook secret?

Without metadata filtering, vector search might return a highly similar runbook from tenant globex. With filtering, the query must include tenant and visibility:

SELECT document_id, content
FROM chunks
WHERE tenant_id = 'acme'
  AND visibility IN ('engineering', 'platform')
  AND deleted_at IS NULL
ORDER BY embedding <=> $query_embedding
LIMIT 8;

The best answer is not the globally most similar chunk. It is the most similar chunk the current user is allowed to read.

Common Mistakes#

• Filtering only after the top vector matches are returned.
• Forgetting document version or deletion state.
• Reusing one global index for tenants with strict isolation needs.
• Dropping metadata during re-embedding pipelines.

Production Considerations#

For large multi-tenant systems, compare one global filtered index against per-tenant or per-segment indexes. The best design depends on tenant size distribution and isolation requirements.

Security#

Treat tenantId, access groups, and sensitivity labels as mandatory fields. Reject chunks without complete authorization metadata during ingestion.

Performance#

Low-selectivity filters are usually cheap. Highly selective filters may need partitioned indexes, pre-filtering, or a higher candidate count to preserve recall.

Summary#

Metadata filtering is not an add-on for vector search. It is the layer that makes semantic retrieval correct, secure, and production-ready.