Metadata filters: enforce eligibility before similarity ranking

Similarity answers “which text looks related?” It does not answer “may this user receive it?” or “which version is active?” Eligibility must constrain the candidate set before ranking and before content reaches a model or trace.

Test a public-only query

The retrieval evaluation lab filters its synthetic corpus first.

from retrieval_cases import metadata_filter_case

result = metadata_filter_case()
assert result["scope"] == "public"
assert result["eligible_ids"] == ["public-help"]
assert result["restricted_in_candidate_set"] is False
assert result["filter_before_ranking"] is True

A query about refund receipts cannot pull staff policies into a public candidate list, even if those documents are textually closer. The test is local and does not establish real identity controls.

Derive scope from authenticated context

Use tenant, role, source permissions, effective interval, jurisdiction and deletion state from trusted application data. Document content cannot change those values. Missing mandatory metadata should fail closed.

Push filters into the search engine where supported. Retrieving a broad top-*k* then removing unauthorized results can expose data and starve the final list of eligible evidence. Test index configuration so filter fields are correctly typed and indexed.

Evaluate security and quality

Create allow/deny pairs, cross-tenant identifiers, revoked roles, public/restricted duplicates and changed policy versions. Verify prohibited IDs never enter candidate results, prompt context, logs or citations. Separately measure recall within the eligible corpus; a secure empty result should produce abstention rather than relaxed filters.

The Generative & Agentic AI course connects eligibility filters to ingestion metadata, MCP identity and adversarial tests.

Exercise

Build a two-tenant corpus with overlapping text. Run 20 authorization tests before measuring retrieval. Remove one metadata value and prove the system fails closed without letting the model infer access.

Continue learning

This article is part of the Retrieval quality and grounded answers sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Hybrid retrieval with reciprocal rank fusion.
• Continue with Reranking: measure the quality and latency trade-off.

Reference: Qdrant filtering documentation.