What is the where_document filter in ChromaDB and how does it differ from where?

ChromaDB provides two types of filters that can be used together or separately: where filters on metadata fields (structured key-value pairs), while where_document filters on the raw text content of the stored documents. Both can be combined in a single query.

import chromadb

client = chromadb.Client()
col = client.create_collection("mixed_docs")
col.add(
    documents=[
        "Python tutorial for beginners with examples",
        "Advanced Python decorators and metaclasses",
        "JavaScript async/await guide",
        "Python data science with pandas and numpy",
        "Rust memory safety tutorial",
    ],
    metadatas=[
        {"lang": "python", "level": "beginner"},
        {"lang": "python", "level": "advanced"},
        {"lang": "js",     "level": "intermediate"},
        {"lang": "python", "level": "intermediate"},
        {"lang": "rust",   "level": "beginner"},
    ],
    ids=["d1","d2","d3","d4","d5"],
)

# where_document: filter on text content
results = col.query(
    query_texts=["programming guide"],
    n_results=5,
    where_document={"$contains": "tutorial"},  # text must contain "tutorial"
)
print(results["ids"])  # d1, d2 (Python tut), d5 (Rust tut) — JS has no "tutorial"

# where_document with NOT
results = col.query(
    query_texts=["programming"],
    n_results=5,
    where_document={"$not_contains": "JavaScript"},
)

# Combine where (metadata) + where_document (text content)
results = col.query(
    query_texts=["learning to code"],
    n_results=3,
    where={"lang": "python"},                    # metadata filter
    where_document={"$contains": "tutorial"},    # content filter
    # Only Python docs whose text contains "tutorial"
)
print(results["documents"])
# Only matches d1: "Python tutorial for beginners with examples"