What distance metrics does ChromaDB support and how do you choose between them?

ChromaDB uses a distance metric to measure how similar two vectors are during nearest-neighbour search. The metric is set at collection creation time and cannot be changed afterward. Choosing the wrong metric for your embedding model can significantly degrade search quality.

import chromadb

# Set metric at collection creation — cannot change later!
collection_cosine = client.create_collection(
    name="text_cosine",
    metadata={"hnsw:space": "cosine"},  # recommended for text
)

collection_l2 = client.create_collection(
    name="general_l2",
    metadata={"hnsw:space": "l2"},  # default if not specified
)

collection_ip = client.create_collection(
    name="normalised_ip",
    metadata={"hnsw:space": "ip"},  # use when vectors are unit-normalised
)

# Query returns "distances" field — interpretation depends on metric:
# cosine: 0 = identical, 2 = opposite (lower = more similar)
# l2:     0 = identical, larger = more different (lower = more similar)
# ip:     more negative = more similar (with normalised vectors)

Rule of thumb: most popular text embedding models (OpenAI, Sentence Transformers) are optimised for cosine similarity. Use "hnsw:space": "cosine" for text RAG applications. L2 is the default but is less optimal for text embeddings that vary in magnitude.