In Chroma, what does the hnsw:space collection metadata set, and what is its default?

## What the setting does A Chroma collection stores its index configuration in the `metadata` dict you supply at creation. The key `hnsw:space` names the distance function used both when the index is built and when a query is scored. Three values are accepted: - `"l2"` — squared Euclidean distance. The default when you say nothing. - `"ip"` — inner product (dot product), expressed so that smaller is closer. - `"cosine"` — cosine distance, i.e. 1 minus cosine similarity. You set it like this: ``` client.get_or_create_collection(name="docs", metadata={"hnsw:space": "cosine"}) ``` ## Why the default is worth thinking about Almost every general-purpose text-embedding model in common use — including the `all-MiniLM-L6-v2` model behind Chroma's default embedding function — is trained with a cosine objective and published with cosine-similarity benchmarks. Its vectors are meaningful in *direction*; their magnitude is an artefact. Squared Euclidean distance is sensitive to magnitude as well as direction. For vectors that happen to be near-uniform in length, L2 and cosine rank very similarly, which is exactly why the mismatch survives casual testing: your demo queries return sensible documents, so nothing looks broken. Where the two diverge is on the tail — long documents, unusual inputs, anything whose vector norm drifts from the pack — and that tail is where retrieval quality is actually decided. The practical rule: match the metric to what your embedding model was trained for. For the common sentence-transformer and hosted text-embedding families, that is cosine. Set it deliberately rather than inheriting the default. Inner product is the right choice when a model is explicitly documented as a dot-product model, or when you have already normalised your vectors — for unit-length vectors, inner product and cosine rank identically, and inner product avoids re-computing norms. ## It is fixed at creation The space is compiled into the index structure, not evaluated per query, so it is not editable after the fact. There is no "change the metric" operation. Changing it means creating a new collection with the right metadata and re-adding the records. The subtler consequence involves `get_or_create_collection`. When the named collection already exists, that call is a *get*: you receive the existing collection, with the metric it was created with. Passing `metadata={"hnsw:space": "cosine"}` to a collection that was born with the L2 default does not upgrade it and does not raise. Code that looks entirely correct — every call site names cosine — can be operating on an L2 index because the very first run, months earlier, forgot the metadata. If you need certainty, inspect the collection's stored metadata rather than trusting the argument you passed. This also means the setting belongs in whatever provisioning step creates the collection, not scattered across every module that obtains a handle to it. ## Distances, not similarities Chroma returns distances in query results, and the direction is consistent across all three spaces: **smaller means closer**. The scale, however, is not. - Under `"cosine"`, the value is 1 − cosine similarity, so it runs from 0 (identical direction) to 2 (opposite), with 1 meaning orthogonal. - Under `"l2"`, it is the *squared* Euclidean distance, unbounded above and quadratic in the actual geometric distance. - Under `"ip"`, it is derived from the dot product and is not bounded to a friendly range at all. So any threshold you hard-code — "drop results with distance above 0.35" — is meaningful only for the space it was tuned in. Moving a collection from L2 to cosine silently invalidates every such constant, and a threshold copied out of a blog post written for a different setup is worse than no threshold. Tune cut-offs against your own data, and record which space they were tuned under. ## Other index settings live in the same dict `hnsw:space` is one of a family of index keys on the same metadata dict; the graph-construction parameters (`hnsw:M`, `hnsw:construction_ef`) and the search-time breadth (`hnsw:search_ef`) sit beside it and follow the usual build-cost-versus-recall tradeoffs. Two practical notes. First, the same dict also holds *your* application metadata, so keep your own keys clearly distinct from the `hnsw:` prefix. Second, the space is the one setting where the default is genuinely likely to be wrong for your model, whereas the graph parameters have defaults that are fine until you have measured a reason to move them.