Chroma cheat sheet: clients, collections, add/upsert, query with where and where_document filters, and housekeeping

#Clients

import chromadb
client = chromadb.HttpClient(host="chroma.internal", port=8000)
client.heartbeat()
client.get_version()

#Collections

col = client.get_or_create_collection(
    name="kb_chunks",
    configuration={"hnsw": {"space": "cosine", "ef_construction": 200, "ef_search": 100}},  # 1.x
    # 0.x: metadata={"hnsw:space": "cosine"}
    embedding_function=None,      # None if you always pass your own embeddings
)

client.list_collections()
client.get_collection("kb_chunks")
client.delete_collection("kb_chunks")
col.count()
col.peek(5)                       # first few items
col.modify(name="kb_chunks_old")  # rename

Collection names: 3–512 characters, letters, digits, ., _, -; must start and end with a letter or digit.

#Add, upsert, update

col.add(
    ids=["doc42#0", "doc42#1"],
    embeddings=[emb0, emb1],
    documents=["chunk text 0", "chunk text 1"],
    metadatas=[{"doc_id": "doc42", "source": "wiki", "year": 2026},
               {"doc_id": "doc42", "source": "wiki", "year": 2026}],
)
col.upsert(ids=[...], embeddings=[...], documents=[...], metadatas=[...])   # insert or replace
col.update(ids=["doc42#0"], metadatas=[{"doc_id": "doc42", "reviewed": True}])

• add with an existing ID doesn't overwrite it; use upsert for idempotent ingestion.
• If you omit embeddings, Chroma embeds documents with the collection's embedding function.
• Metadata values: str, int, float, bool (newer versions add array support; check your version). No None, no nested dicts.
• Very large batches can hit the server's maximum batch size: client.get_max_batch_size() (newer versions) tells you the limit.

#Query

res = col.query(
    query_embeddings=[qvec],
    n_results=10,
    where={"source": "wiki"},
    where_document={"$contains": "VPN"},
    include=["documents", "metadatas", "distances"],
)
for i, d, m, dist in zip(res["ids"][0], res["documents"][0], res["metadatas"][0], res["distances"][0]):
    print(i, round(dist, 3), m["doc_id"])

Results are lists per query embedding, hence [0]. include options: documents, metadatas, distances, embeddings (embeddings are large; include only when needed).

#Metadata filters (where)

A where with two keys at the top level ({"a": 1, "b": 2}) raises an error; use $and.

#Document filters (where_document)

$contains is case-sensitive substring matching, not ranked full-text search.

#Get (no vector search)

col.get(ids=["doc42#0"], include=["documents", "metadatas"])
col.get(where={"doc_id": "doc42"}, include=["metadatas"])
col.get(limit=500, offset=1000, include=["embeddings"])      # paging for exports

#Delete

col.delete(ids=["doc42#0", "doc42#1"])
col.delete(where={"doc_id": "doc42"})

Caution

In some versions col.delete() with neither ids nor where could delete everything or raise; never call it without arguments. To empty a collection, delete and recreate it.

#Distances

Set space explicitly when creating a collection; it can't be changed later.

#Common errors

#Tenants and databases

The server has tenants and databases (defaults default_tenant / default_database). Pass them when you use more than the default:

client = chromadb.HttpClient(host="chroma", port=8000, tenant="team-a", database="kb")

#Prevent mistakes next time

• Use upsert with deterministic IDs (doc_id#chunk).
• Set space explicitly; pass query_embeddings from the same model as ingestion.
• Keep metadata flat and typed; no None.
• Never call delete() without a selector.