ChromaDB Collections

A collection defines a retrieval boundary. Stable IDs, metadata and deletion/archive policy become increasingly important as the corpus grows.

#Collection operations

pythonCopy
collection = client.create_collection(name="test_name")
collection = client.get_or_create_collection(name="test_name")
collection = client.get_collection(name="test_name")
# Destructive: removes the named collection.
# client.delete_collection(name="test_name")

#Record fields

ids identify records. embeddings hold supplied vectors. documents hold source text and can be embedded by a configured function. metadatas hold filterable attributes. Field requirements and valid combinations should match the client version.

Agree on IDs and useful fields such as source, language, document type and update time. These are retrieval decisions as well as maintenance conventions.

#Update or upsert

pythonCopy
collection.update(ids=["id1"], metadatas=[{"status": "archived"}])
collection.upsert(
    ids=["id1", "id3"],
    documents=["Updated content", "New content"],
)
# Destructive examples; review the target first:
# collection.delete(ids=["id1"])
# collection.delete(where={"status": "archived"})

#Filter the query

pythonCopy
results = collection.query(
    query_texts=["Find relevant guidance"],
    where={"source": "notion"},
    n_results=5,
)
results = collection.query(
    query_texts=["Find relevant guidance"],
    where_document={"$contains": "important"},
)

#Distance metrics

The source discusses squared L2, inner product and cosine distance, with a legacy metadata={"hnsw:space": "cosine"} configuration example. Check your installed Chroma version's collection configuration API before copying it.

Evaluate chunking and metadata before repeatedly switching metrics. Relevant boundaries often matter more than changing the distance formula.

#Next step

• Embedding functions