How do you interpret ChromaDB query distances and convert them into meaningful relevance scores?

ChromaDB query results include a distances field. The interpretation depends on the distance metric. Raw distances are not directly comparable across metrics, but they can be normalised into a [0, 1] relevance score for display or thresholding.

import chromadb

client = chromadb.Client()
col = client.create_collection("relevance_demo", metadata={"hnsw:space": "cosine"})
col.add(
    documents=[
        "ChromaDB is an open-source vector database",
        "Python is a popular programming language",
        "The Eiffel Tower is in Paris France",
    ],
    ids=["d1","d2","d3"],
)

results = col.query(
    query_texts=["vector database for AI"],
    n_results=3,
    include=["documents","distances"],
)

raw_distances = results["distances"][0]
print("Raw cosine distances:", raw_distances)
# e.g. [0.18, 0.72, 1.31]
# cosine distance: 0 = identical, 2 = completely opposite

# Convert cosine distance to similarity score [0, 1]
def cosine_distance_to_score(distance: float) -> float:
    """cosine distance [0,2] → relevance score [0,1]"""
    return 1 - (distance / 2)

for doc, dist in zip(results["documents"][0], raw_distances):
    score = cosine_distance_to_score(dist)
    print(f"  Score: {score:.3f} | {doc[:50]}")
# Score: 0.910 | ChromaDB is an open-source vector database
# Score: 0.640 | Python is a popular programming language
# Score: 0.345 | The Eiffel Tower is in Paris France

# Threshold: only return results above minimum relevance
MIN_SCORE = 0.7
filtered = [
    (doc, cosine_distance_to_score(dist))
    for doc, dist in zip(results["documents"][0], raw_distances)
    if cosine_distance_to_score(dist) >= MIN_SCORE
]
print(f"\nResults above {MIN_SCORE} threshold: {len(filtered)}")
for doc, score in filtered:
    print(f"  {score:.3f}: {doc}")