What does Chroma's include parameter control in query(), and what comes back by default?

## What include is for A Chroma result row can carry several parallel pieces of data: the id, the document text, the metadata dictionary, the distance to the query point, the raw embedding, and (for multimodal collections) uris and data. `include` chooses which of these travel back. It is orthogonal to `where` and `where_document`: those decide *which records* qualify, `include` decides *what each record brings with it*. Setting `include=["distances"]` does not remove records — it just leaves the documents out of the payload. ## The defaults, and the one deliberate omission `query()` returns documents, metadatas and distances by default. `get()` returns documents and metadatas; there is no distance because `get` has no query vector to measure against. Embeddings are in neither default, and that is a considered choice. A collection using a 1536-dimensional model returns roughly 1536 floats per hit. Ask for twenty hits and the vector payload is far larger than every document and metadata field combined. Most callers — a RAG prompt builder, a UI result list — never look at the vectors, so shipping them is pure waste. You request `"embeddings"` when you genuinely need the numbers: computing your own re-ranking, clustering the neighbourhood, debugging a suspected model mismatch, or migrating vectors elsewhere. Ids are a special case: they are always in the response and are not something you put in `include`. Every result row is addressable, always. ## Reading distances The field is named `distances`, not `scores`, and the naming is the whole point: **smaller means closer**. Sorting ascending gives you best-first, which is already the order Chroma returns. Two follow-on facts matter in practice. First, the numeric scale depends on the distance space chosen when the collection was created — the default space is a squared-L2 distance, and cosine-configured collections produce a different range. So a raw threshold like "drop anything above 0.8" is only meaningful once you know the space, and it does not transfer between collections configured differently. Second, distances are not calibrated probabilities. Converting them into a confidence percentage for a UI is a fabrication unless you have empirically mapped distances to relevance on your own data. The defensible use of the number is *relative*: comparing hits within one result set, or watching the distribution shift over time as a regression signal. ## The response shape `query()` returns a dictionary whose values are nested one level per query — `res["documents"][0]` is the document list for the first query, `res["distances"][0][2]` the distance of the third hit for the first query. Fields you did not include are still present as keys but hold no data, so code that blindly indexes `res["embeddings"][0][0]` after trimming `include` fails at read time rather than at call time. The response also reports which fields were included, so defensive code can check rather than assume. `get()` returns flat lists instead — one level, because there is no batch of queries. Code that copies an indexing pattern from `query` to `get` and keeps the `[0]` is a common and confusing bug: it silently takes the first element instead of the whole list. ## When trimming actually matters Against an in-process `PersistentClient`, trimming `include` saves object construction and little else. Against an HTTP server, every unused field is serialised, pushed over the wire and parsed by the client — and that is where a 20-hit query returning unnecessary embeddings shows up as latency and bandwidth on a hot path. The habit worth having is to name exactly the fields the caller consumes: a retrieval step feeding an LLM prompt usually needs `["documents"]` plus `["distances"]` if it thresholds, and nothing more. The inverse habit is worth naming too: do not reach for `"embeddings"` to "check that things are working". `collection.count()` and a small `peek()` answer that question far more cheaply.