In Chroma's query(), how do the where and where_document filters differ?

## Two filters over two different fields Every record Chroma stores is an id, a vector, an optional document string, and an optional metadata dictionary. The query API gives you one filter per non-vector field: - `where` filters the **metadata dictionary**. - `where_document` filters the **document text**. Both are optional, both narrow the candidate set before you get results, and when you pass both, a record must satisfy both. ## The where syntax Metadata filtering uses a small Mongo-flavoured operator set: - Equality: `$eq`, `$ne` - Ordering: `$gt`, `$gte`, `$lt`, `$lte` - Membership: `$in`, `$nin` - Composition: `$and`, `$or`, each taking a list of clauses A bare mapping is sugar: `where={"source": "handbook"}` means `{"source": {"$eq": "handbook"}}`. Several keys in one dict are combined with AND, so `{"source": "handbook", "year": {"$gte": 2024}}` requires both. When you need OR, you must say it explicitly with `$or`. The hard constraint people trip over is the **value type**. Chroma metadata values are scalars only: `str`, `int`, `float`, `bool`. You cannot store `{"tags": ["a", "b"]}` and you therefore cannot filter "has tag a". The two standard workarounds are to explode the list into boolean keys (`{"tag_a": True, "tag_b": True}`), which filters cleanly, or to store a delimited string and reach for `where_document`-style substring logic, which is fragile. The boolean-key approach is generally the right one; it costs metadata width but keeps filters exact. A second silent trap is **type consistency across records**. If some records store `{"year": 2024}` and others `{"year": "2024"}`, a range filter matches only the numeric ones and quietly drops the rest. Normalise types at write time. ## The where_document syntax `where_document={"$contains": "deadlock"}` keeps records whose document text contains that literal substring. `$not_contains` inverts it. You can compose these with `$and` / `$or` to express things like "mentions retry but not deprecated". What matters is what this is *not*. It is a substring test, not an inverted-index keyword search: there is no tokenisation, no stemming, no case-normalisation guarantee to lean on, and — crucially — **no contribution to the ranking**. A document that mentions the term forty times ranks exactly the same as one that mentions it once; the ordering is still purely vector distance among the surviving records. If the interview question is really "how do I blend keyword relevance with vector relevance", the honest answer is that this filter does not do that, and Chroma is not the tool you would reach for. ## How they interact with the search Chroma resolves the filters against its metadata store to obtain the set of ids that qualify, and restricts the nearest-neighbour search to that set. Two consequences follow. First, `n_results` counts *matching* records, so a filter never causes you to receive fewer results than exist in the filtered set — unlike systems that filter after taking a fixed candidate pool and then hand back a short list. Second, the cost of a query grows with how much of the collection the filter excludes, because the restricted search loses the benefit of the graph structure as the allowed set shrinks. The same two filters are accepted by `collection.get()` and by `collection.delete()`. `get(where=..., where_document=...)` is a pure filter scan with no query vector at all, which is the right tool for "show me every record from this source". `delete(where=...)` deletes everything that matches, which is powerful and unforgiving — run it as a `get` first and look at the count. ## Designing metadata for filtering Because filters are exact and typed, the quality of your filtering is decided at ingest time, not query time. Decide the small set of fields you will actually filter on — source, tenant, document type, timestamp bucket, language — and write them consistently on every record. Free-form metadata that varies by ingestion path produces filters that appear to work and silently miss data, which is far worse than a filter that errors.