Chroma Cheatsheet: Collections, Queries and Filters Reference

# Python client — covers both local and server modes
pip install "chromadb>=0.5"

# Docker — single-node server (HTTP API on :8000)
docker run -p 8000:8000 -v chroma:/data \
  -e IS_PERSISTENT=TRUE -e PERSIST_DIRECTORY=/data \
  chromadb/chroma:latest

# CLI — run the server from the package
chroma run --path ./chroma_data --host 0.0.0.0 --port 8000

# JS / TS client
npm install chromadb chromadb-default-embed

from chromadb.utils import embedding_functions

# Default — onnx all-MiniLM-L6-v2, ships with the package, no API key
default_ef = embedding_functions.DefaultEmbeddingFunction()

# OpenAI
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key=os.environ["OPENAI_API_KEY"],
    model_name="text-embedding-3-small",
)

# Sentence-Transformers — runs locally on CPU/GPU
st_ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="BAAI/bge-small-en-v1.5"
)

# Custom — any callable that maps list[str] -> list[list[float]]
class MyEF(embedding_functions.EmbeddingFunction):
    def __call__(self, input):
        return [[0.0] * 384 for _ in input]

# Attach to a collection — once set, you don't pass embeddings yourself
col = client.get_or_create_collection("docs", embedding_function=openai_ef)

# Metadata filter — "where" mirrors Mongo-style operators
res = col.query(
    query_texts=["how does retrieval work?"],
    n_results=5,
    where={
        "$and": [
            {"source": {"$eq": "docs"}},
            {"year":   {"$gte": 2024}},
            {"tag":    {"$in": ["rag", "embeddings"]}}
        ]
    },
    where_document={"$contains": "vector"},   # full-text filter on the chunk
)

# Operators reference:
#   $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin   — value comparisons
#   $and, $or                                    — boolean composition
#   $contains, $not_contains                     — document text (where_document)

# Update / delete by filter — no need to pass ids
col.update(ids=["a", "b"], metadatas=[{"reviewed": True}, {"reviewed": True}])
col.delete(where={"year": {"$lt": 2020}})

# Minimal RAG store — persistent client, one collection, query with a filter
import chromadb
from chromadb.utils import embedding_functions

client = chromadb.PersistentClient(path="./chroma_data")

ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="BAAI/bge-small-en-v1.5"
)

col = client.get_or_create_collection(
    name="kb",
    embedding_function=ef,
    metadata={"hnsw:space": "cosine"},   # cosine ∈ [0,2], lower is closer
)

# Index — Chroma embeds documents for you because ef is set
col.upsert(
    ids        = ["d1", "d2", "d3"],
    documents  = ["Vectors are dense embeddings.",
                  "RAG joins retrieval with generation.",
                  "Chroma is local-first."],
    metadatas  = [{"source": "blog"},
                  {"source": "docs"},
                  {"source": "docs"}],
)

# Retrieve top-2 docs from "docs" only
hits = col.query(
    query_texts=["what is RAG?"],
    n_results=2,
    where={"source": "docs"},
)
for d, m, dist in zip(hits["documents"][0], hits["metadatas"][0], hits["distances"][0]):
    print(f"{dist:.3f}  [{m['source']}]  {d}")