Metadata — Module 14.1

How This Lesson Fits the Module & Volume

Vectors alone cannot express “only this tenant,” “docs after 2025,” or “cite page 12.” Metadata attached to each chunk enables filtered hybrid/vector search, ACLs, and citations. It is the bridge between the knowledge base and safe retrieval.

Learning Objectives

By the end of this lesson, students should be able to:

Define chunk metadata and list fields every RAG index should store.
Use metadata filters (pre- or post-filter) without killing recall.
Design tenant / ACL fields for multi-user knowledge bases.
Support citations via source URI, offsets, titles, and versions.
Version embedding-model IDs alongside chunk rows.
Avoid over-filtering that silently drops gold documents.

Definition

Metadata in RAG is structured side information stored with each indexed chunk—source identity, timestamps, access control, section titles, offsets, and operational tags—used for filtering, ranking boosts, and citation.

Core Fields

Field	Purpose
`source_id` / URI	Provenance & dedupe
`title` / `section`	Human citations & boosts
`start`, `end`	Highlight original span
`updated_at`	Freshness filters
`tenant` / `acl`	Authorization
`embed_model`	Index/query compatibility

Pre-filter

ANN only in subset
Needs index support
Strong ACL fit

Post-filter

Search then drop
May underfill k
Simple to start

Soft boost

Prefer recent/title hit
Keep others
Tunable weights

Code: Metadata-Aware Retrieve

from datetime import date

chunks = [
    {"id": "1", "text": "Refund window is 30 days.", "tenant": "acme", "updated": date(2026, 1, 10)},
    {"id": "2", "text": "Refund window is 14 days.", "tenant": "beta", "updated": date(2024, 5, 1)},
    {"id": "3", "text": "Shipping SLA is 5 days.", "tenant": "acme", "updated": date(2026, 3, 1)},
]

def filter_chunks(rows, tenant: str, min_updated: date | None = None):
    out = [r for r in rows if r["tenant"] == tenant]
    if min_updated:
        out = [r for r in out if r["updated"] >= min_updated]
    return out

# Always filter BEFORE trusting scores for multi-tenant RAG.
visible = filter_chunks(chunks, tenant="acme", min_updated=date(2025, 1, 1))
print([c["id"] for c in visible])

Strengths

Enables security & tenancy
Makes citations real
Supports freshness policies

Tradeoffs

Schema drift across sources
Over-filtering kills recall
ACL bugs = data leaks

Common Misconception

“We’ll put access control in the LLM prompt.” Prompts are not a security boundary. Enforce ACLs in retrieval filters (and the document store). The model must never see unauthorized chunks.

Knowledge Check

Short Answer: Name three useful metadata fields. Answer: source_id, tenant/ACL, updated_at, offsets, embed_model (any three).
True/False: Prompt instructions are enough for multi-tenant ACL. Answer: False.
Multiple Choice: Post-filtering risk: (a) underfilling top-k, (b) faster GPUs, (c) free tokens. Answer: (a).
Short Answer: Why store embed_model? Answer: Ensure query encoding matches the index space.
True/False: Offsets help citation highlighting. Answer: True.
Multiple Choice: Soft boosts: (a) prefer some docs without hard drops, (b) delete the index, (c) CSS only. Answer: (a).
Short Answer: What is over-filtering? Answer: Predicates so strict that gold docs never enter candidates.
True/False: Metadata is only for analytics, not retrieval. Answer: False.
Multiple Choice: Next lecture: (a) Re-ranking, (b) Vol. 1 only, (c) printers. Answer: (a).
Short Answer: Where should ACL be enforced? Answer: In retrieval/storage filters, not only in the prompt.

Key Takeaways

Metadata powers filters, ACLs, freshness, and citations.
Enforce security in retrieval—not in prompt text alone.
Design schema early; avoid over-filtering.
Next: Re-ranking.

Trainer’s Guide

Lab: Two tenants share similar FAQs; prove a missing tenant filter leaks answers.

Prompt: Pre-filter vs post-filter for a 50M-vector HNSW index?

Recap: Metadata turns raw vectors into a governed knowledge index. Continue with Re-ranking.