ChromaDB Query Cheat Sheet

Clients

Install with pip install chromadb. Every example on this page uses a client named client and a collection named docs.

Settings comes from chromadb.config. The JavaScript client (npm install chromadb) uses camelCase for the same calls: nResults, queryTexts, whereDocument, and it needs @chroma-core/default-embed installed for the default embedding model.

Example: open a local database with telemetry off and confirm it responds.

import chromadb
from chromadb.config import Settings

client = chromadb.PersistentClient(
    path="./chroma",
    settings=Settings(anonymized_telemetry=False),
)
print(client.heartbeat(), chromadb.__version__)

Collections

A collection is Chroma's table: records with an ID, a document, metadata and an embedding.

The distance space is l2 unless you pass cosine or ip, and it cannot change later. Names need 3 to 512 characters from a-z A-Z 0-9 . _ -. get_collection raises NotFoundError for a missing name, and create_collection raises an "already exists" error for a taken one.

Example: create the support_docs collection used on the rest of this page, with cosine distance.

docs = client.get_or_create_collection(
    name="support_docs",
    configuration={"hnsw": {"space": "cosine"}},
    metadata={"team": "support"},
)
print(docs.configuration["hnsw"])

In 1bench: the Chroma GUI has a schema view per collection that shows the tenant and database, the embedding function, the distance space and every HNSW setting, so you do not have to print docs.configuration to check them.

Add and Upsert

add skips an ID that already exists and raises no error, so the old record stays. Use upsert when a record may already be there.

Example: load four support articles with source, category and year metadata.

docs.add(
    ids=["doc1", "doc2", "doc3", "doc4"],
    documents=[
        "How to reset your password from the login page",
        "Refunds are issued within 5 business days",
        "Enable two-factor authentication in account settings",
        "Export your invoices as PDF from the billing page",
    ],
    metadatas=[
        {"source": "help_center", "category": "account", "year": 2025},
        {"source": "faq", "category": "billing", "year": 2024},
        {"source": "help_center", "category": "security", "year": 2026},
        {"source": "faq", "category": "billing", "year": 2026, "tags": ["pdf", "invoice"]},
    ],
)
print(docs.count())

A call with more records than get_max_batch_size() (5461 in our test) fails with "Batch size ... is greater than max batch size". Split big loads:

batch = client.get_max_batch_size()
for i in range(0, len(ids), batch):
    docs.upsert(
        ids=ids[i:i + batch],
        documents=texts[i:i + batch],
        metadatas=metas[i:i + batch],
    )

Get vs Query

get reads records by ID or filter with no ranking. query runs a similarity search and returns the nearest records first. Both take where, where_document and include.

Defaults: get returns metadatas and documents, query adds distances. get with include=["distances"] raises an error. query returns one list per query text, so read r["ids"][0], not r["ids"]. Asking for more n_results than there are records returns them all.

Example: the two closest articles to a user question, with their distances.

r = docs.query(
    query_texts=["I forgot my password"],
    n_results=2,
    include=["documents", "metadatas", "distances"],
)
for doc_id, text, dist in zip(r["ids"][0], r["documents"][0], r["distances"][0]):
    print(doc_id, round(dist, 3), text)

Metadata Filters

where filters on metadata in both get and query. Each dict holds exactly one field or one operator.

Two keys in one dict, such as {"source": "faq", "year": 2026}, raise "Expected where to have exactly one operator". Wrap them in $and. Comparison operators check types too: {"year": {"$gt": "2024"}} fails because the value is a string.

Example: FAQ billing articles, nearest to a refund question.

r = docs.query(
    query_texts=["how long does a refund take"],
    n_results=3,
    where={"$and": [{"source": "faq"}, {"category": "billing"}]},
)
print(r["ids"][0])

In 1bench: the Chroma GUI has a query builder with Query and Get modes, an IDs box, a where JSON field and a where_document field with a negate switch, and it shows the request body it will send.

Document Filters

where_document filters on the document text. Use it alone with get, or next to where in a query.

$contains is case-sensitive: {"$contains": "PASSWORD"} does not match "password". Use $regex with (?i) when case should not matter.

Example: billing articles that mention PDF, ranked against an invoice question.

r = docs.query(
    query_texts=["download my invoice"],
    n_results=2,
    where={"category": "billing"},
    where_document={"$contains": "PDF"},
    include=["documents", "distances"],
)
print(r["documents"][0], r["distances"][0])

Update and Delete

update on an ID that does not exist raises no error and changes nothing. docs.delete() with no arguments raises an error instead of emptying the collection.

Example: retire every pre-2025 FAQ article and bump the year on one that was reviewed.

docs.delete(where={"$and": [{"source": "faq"}, {"year": {"$lt": 2025}}]})
docs.update(ids=["doc1"], metadatas=[{"year": 2026}])
print(docs.count(), docs.get(ids=["doc1"])["metadatas"])

In 1bench: the Chroma GUI exports a whole collection to a JSON file, with or without embeddings, so you can keep a copy before a bulk delete.

Embedding Functions

A collection embeds documents and query_texts with its embedding function. Pass one at creation; Chroma saves the choice in the collection configuration.

The default model downloads about 80 MB to ~/.cache/chroma/onnx_models on first use. The OpenAI function reads its key from CHROMA_OPENAI_API_KEY unless you set api_key_env_var, and only the variable name is saved, never the key. get_collection restores a built-in function from the saved configuration, and passing a different one raises "Embedding function conflict".

Example: a collection embedded with OpenAI, reopened later without passing the function again.

from chromadb.utils import embedding_functions

openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key_env_var="OPENAI_API_KEY",
    model_name="text-embedding-3-small",
)
kb = client.get_or_create_collection("support_docs_openai", embedding_function=openai_ef)
kb.add(ids=["doc1"], documents=["How to reset your password from the login page"])

kb = client.get_collection("support_docs_openai")
print(kb.query(query_texts=["lost password"], n_results=1)["ids"])

Full-Text and Hybrid Search

In chromadb 1.5.9, a local or self-hosted server rejects sparse indexes and collection.search(). The Search API below runs on Chroma Cloud:

from chromadb import Search, K, Knn

s = (
    Search()
    .where(K("category") == "billing")
    .rank(Knn(query="get my money back"))
    .limit(2)
    .select(K.DOCUMENT, K.SCORE, "year")
)
results = docs.search(s)

Example: a local stand-in for hybrid search, ranking by meaning and keeping only articles that mention a password.

r = docs.query(
    query_texts=["I cannot log in"],
    n_results=3,
    where_document={"$regex": "(?i)password"},
)
print(r["ids"][0], r["distances"][0])

CLI, Server and REST API

The chroma command ships with the Python package.

REST calls under /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/ take the collection UUID, not its name, for get, query, add, upsert, update, delete and count. The server does not embed text, so a REST query needs query_embeddings.

Example: start a server on port 8000 and fetch billing articles over REST.

chroma run --path ./chroma-data --port 8000

B=http://localhost:8000/api/v2/tenants/default_tenant/databases/default_database
ID=$(curl -s "$B/collections/support_docs" | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")

curl -s -X POST "$B/collections/$ID/get" \
  -H 'Content-Type: application/json' \
  -d '{"where": {"category": "billing"}, "include": ["documents", "metadatas"]}'

Gotchas

• add with an existing ID keeps the old record and raises no error, and update on a missing ID does nothing silently. Use upsert when you are not sure the record exists.
• A where dict with two fields raises "Expected where to have exactly one operator". Write {"$and": [{"source": "faq"}, {"year": 2026}]}, not {"source": "faq", "year": 2026}.
• get_or_create_collection on an existing collection ignores the configuration you pass, so a collection first created with l2 stays l2. The space cannot be changed later; create a new collection and copy the records.
• add, upsert and delete fail above client.get_max_batch_size() records per call. Split large loads into batches.
• where_document $contains is case-sensitive. Use $regex with (?i) for a case-insensitive match.
• Embeddings come back as a NumPy array, so if r["embeddings"]: raises "truth value of an array ... is ambiguous". Check is not None or len() instead.