How do you design metadata schemas for effective filtering in ChromaDB?

Metadata in ChromaDB is stored as flat key-value dictionaries where values must be strings, integers, or floats (not nested dicts or lists). Good metadata design makes the difference between fast, precise filtered queries and slow full-collection scans.

import chromadb
from datetime import datetime

client = chromadb.Client()
col = client.create_collection("knowledge_base")

# Good metadata design — flat, filterable fields
col.add(
    documents=[
        "Introduction to transformer architecture in deep learning.",
        "BERT: Pre-training of Deep Bidirectional Transformers.",
        "GPT-4 technical report overview.",
    ],
    metadatas=[
        {
            "source":    "textbook",
            "author":    "Vaswani",
            "year":      2017,           # int — supports $gt, $lt
            "category":  "architecture",
            "citations": 50000,          # int — sortable
            "language":  "en",
            # timestamp as int for range queries
            "added_ts":  int(datetime(2024,1,1).timestamp()),
        },
        {
            "source":    "paper",
            "author":    "Devlin",
            "year":      2018,
            "category":  "pretraining",
            "citations": 40000,
            "language":  "en",
            "added_ts":  int(datetime(2024,1,2).timestamp()),
        },
        {
            "source":    "report",
            "author":    "OpenAI",
            "year":      2023,
            "category":  "LLM",
            "citations": 5000,
            "language":  "en",
            "added_ts":  int(datetime(2024,1,3).timestamp()),
        },
    ],
    ids=["p1","p2","p3"],
)

# Effective filtered queries
results = col.query(
    query_texts=["neural network architecture"],
    n_results=5,
    where={"$and": [
        {"year":     {"$gte": 2017}},
        {"citations":{"$gte": 10000}},
        {"language": "en"},
    ]},
)

# Anti-patterns to avoid in metadata:
# BAD:  {"tags": ["python", "nlp"]}  — lists not supported
# BAD:  {"author": {"name": "Vaswani", "affiliation": "Google"}}  — nested not supported
# GOOD: {"tag_python": 1, "tag_nlp": 1}  — flatten list membership to bool ints
# GOOD: {"author_name": "Vaswani", "author_org": "Google"}  — flatten nested