The Complete Chroma Guide

This is part one of three. It covers everything you need to do real work with Chroma, not a teaser. By the end you can store text in a collection, search it by meaning, narrow the search with filters, keep your data on disk between runs, move from a script to a running server, and read the error messages you will meet along the way. Mid-level and Senior take the same topics further; nothing here is thrown away.

Every command and example was checked against Chroma 1.5.9, the current stable release. Pin that version when you follow along. Each section ends with a Try it task. Do them as you go: search by meaning only feels real once you have watched your own sentences come back in a surprising but sensible order.

What Chroma is, and the problem it solves

Chroma is an open-source database built for retrieval: you give it pieces of text (or other data), and later you ask a question and it hands back the pieces most relevant to that question. It is licensed Apache-2.0, and its own documentation describes it as open-source data infrastructure for AI.

To see why this needs a special kind of database, start with how ordinary search works. A classic database finds rows where a column equals a value, or where a string contains a word. If you search a help centre for "my card was declined" and the relevant article says "payment failed", a keyword search finds nothing, because the two sentences share no words. A human sees at once that they mean the same thing. Chroma exists to close that gap.

The trick is the embedding. An embedding is a list of numbers, a vector, that a machine learning model produces from a piece of text so that texts with similar meaning get similar numbers. "My card was declined" and "payment failed" end up close together in that number space, even though they share no words. Searching then becomes geometry: turn the question into a vector, find the stored vectors nearest to it, and return the text they came from.

The diagram is the whole idea. Everything else in this guide is detail about one of those four boxes.

Why does anyone need this now? Large language models (LLMs) answer from what they learned in training, which does not include your company's contracts, your wiki, or yesterday's tickets. The standard remedy is retrieval-augmented generation, usually shortened to RAG: before asking the model a question, you first retrieve the few passages from your own data that are relevant, and paste them into the prompt. Chroma is the retrieval half. It is not the model, and it does not write answers. It finds the right passages, quickly, so the model has something true to work from.

What people use it for:

Chroma runs in three ways, and it helps to know all three from the start. Local means it runs inside your Python process as a library, which is ideal for learning and prototypes. Single-node means one Chroma server that your applications talk to over the network; the documentation positions this for small to medium workloads, typically fewer than ten million records across a handful of collections. Distributed means a multi-service deployment for very large workloads, and Chroma Cloud is the managed version of that. This guide teaches local and single-node, which is where every learner should begin. The API you learn is almost the same in all of them.

The model: tenants, databases, collections and records

Chroma has a small number of nouns. Learn them now and the API will read like plain English.

A record is one stored item. It has a required id, which is a string you choose and which must be unique within its collection. It usually has a document, the text itself. It has an embedding, the vector for that text. It may have metadata, a flat dictionary of small facts about the item such as its source file, page number or author. It can also carry a uri, a pointer to where the original lives. Beginners work mostly with id, document and metadata, and let Chroma compute the embedding.

A collection is a named group of records. It is the fundamental unit of storage and querying in Chroma, and each collection is indexed independently. If you are coming from relational databases, a collection is roughly a table, though a better mental picture is a folder of related notes that you search together. You would keep your support articles in one collection and your product descriptions in another, because you rarely want a question about a refund to return a product description.

Above the collection sit two larger containers. A database is a logical namespace for an application or environment, for instance one for testing and one for production. A tenant is the top-level unit, standing for a user, team or account. When you create a client without specifying either, Chroma uses default_tenant and default_database, and you can ignore both for a long time. They matter later, when one server hosts several teams, and the senior track covers them.

Two rules about collections catch beginners early. First, a collection name must be between 3 and 512 characters, drawn from letters, digits, dots, underscores and hyphens, and it must start and end with a letter or digit. A name like a is rejected, as is -notes. Second, every embedding in a collection must have the same number of dimensions, and the first record you add fixes that number. This is why you cannot mix vectors from two different embedding models in one collection, a point we return to in the errors section.

There is one more noun worth meeting now: the client. A client is the object your code uses to talk to Chroma. You create one, and then every operation, such as creating a collection, goes through it. Which client you create decides where the data lives, and that is the next decision after you install the tool.

Embeddings, distance and the embedding function

You can use Chroma for a long time without understanding embeddings in depth, but three ideas will save you from confusing bugs.

The first is the embedding function, shortened to EF. An embedding function is the piece of code that turns text into a vector. In Chroma you attach one to a collection, and then add and query call it for you whenever you hand over plain text. If you never specify one, Chroma uses its default, a small, fast, well-known model called all-MiniLM-L6-v2 from the Sentence Transformers family, which produces vectors of 384 numbers. In Python it runs locally through ONNX, so no API key is needed. The first time it is used, it downloads the model to ~/.cache/chroma/onnx_models. That one-time download is why your very first add takes longer than the rest, and why it fails on a machine with no internet access.

You can replace the default with a model from a provider such as OpenAI, Cohere, Google, Hugging Face, Ollama, Mistral, Jina or Voyage. Chroma ships ready-made embedding functions for these, and you pass one when you create the collection. You can also skip embedding functions entirely and supply your own vectors, in which case Chroma stores them as given. The beginner path is to use the default and revisit the choice once the first project works.

The second idea is distance. When you query, Chroma returns records nearest to your question, and "nearest" needs a definition. Chroma offers three: l2 (squared Euclidean distance), cosine (one minus cosine similarity) and ip (one minus the inner product). The default is l2. For all of them, a lower number means more similar, so the best match has the smallest distance. Many learners expect a high score to mean a good match, as in a percentage, and misread the output by exactly that inversion. For text embeddings, cosine is the most common choice by convention, and you choose it when you create the collection. The space is fixed at creation and cannot be changed later, which is worth remembering before you load a million records.

The third idea is that the same model must embed both the stored text and the question. A vector is only meaningful relative to the model that produced it. If you add documents with one model and query with another, you will either hit a dimension error or, worse, get plausible-looking nonsense when the dimensions happen to match. Chroma helps by remembering the embedding function inside the collection configuration since version 1.1, so a collection you reopen later uses the same one automatically. API keys are not stored, though. If your embedding function needs one, such as OPENAI_API_KEY, every process that uses the collection must have that environment variable set.

Installing Chroma and checking the setup

Chroma installs as an ordinary Python package. Use a virtual environment so the install stays tidy, and pin the version so your results match this guide.

python -m venv .venv
source .venv/bin/activate          # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install "chromadb==1.5.9"

The package requires Python 3.9 or newer, and Python 3.14 has been supported since 1.5.3. Prebuilt wheels include the compiled Rust core, so you do not normally need a compiler. Installing chromadb also installs the chroma command-line tool, which you will use to run a server and to browse your data. If your system blocks global pip installs, pipx install chromadb is the alternative for the command-line tool.

Verify the setup with two commands:

chroma --version
python -c "import chromadb; print(chromadb.__version__)"

The second command should print 1.5.9. If it prints a different number, you may have an older install shadowing the new one, usually because you forgot to activate the virtual environment.

There are other ways in, and you will meet them in tutorials. JavaScript and TypeScript developers use npm install chromadb @chroma-core/default-embed, and the JavaScript client always needs a running server. There is a standalone command-line installer for people without Python or Node, and an official Docker image, chromadb/chroma:1.5.9. There is also a thin Python package, chromadb-client, meant for applications that only talk to a remote server; install it instead of chromadb, not alongside it, and remember that it has no default embedding function. This guide uses the full chromadb package throughout.

Three platform notes will save you an afternoon. Chroma needs SQLite newer than 3.35; on an old Linux system the official troubleshooting page suggests pip install pysqlite3-binary, and inside Docker you should use a Debian bookworm base or newer. If a build ever fails with Failed to build hnswlib, you are building from source rather than using a wheel, and setting HNSWLIB_NO_NATIVE=1 or installing the Xcode command-line tools on macOS usually helps. And if your employer routes traffic through a TLS-inspecting proxy, the first model download can fail with [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain. The fix is to make Python trust your company's root certificate, for example through the SSL_CERT_FILE environment variable, or to copy the model into ~/.cache/chroma/onnx_models from a machine that can download it. Do not turn certificate verification off.

Your first project: a searchable knowledge base

Now build something. We will store a handful of help-centre sentences, search them by meaning, and read the results. Create a file called first.py.

import chromadb

client = chromadb.EphemeralClient()
collection = client.create_collection(name="help_centre")

collection.add(
    ids=["a1", "a2", "a3", "a4"],
    documents=[
        "Your payment failed because the card was declined.",
        "To reset your password, use the link on the sign-in page.",
        "Refunds are issued to the original payment method within five days.",
        "Preheat the oven to 180 degrees before baking the bread.",
    ],
    metadatas=[
        {"topic": "billing"},
        {"topic": "account"},
        {"topic": "billing"},
        {"topic": "recipes"},
    ],
)

results = collection.query(
    query_texts=["I want my money back"],
    n_results=2,
)
print(results)

Run it with python first.py. The first run pauses while the default embedding model downloads, then prints a dictionary. Let us walk through what happened, because each line teaches one idea.

chromadb.EphemeralClient() creates a client that keeps everything in memory. When the script ends, the data is gone. That makes it the safest place to experiment, because there is nothing to clean up. create_collection(name="help_centre") creates a collection with the default embedding function and the default distance.

collection.add(...) stores four records. We passed ids, documents and metadatas as three parallel lists, so the first id goes with the first document and the first metadata dictionary. We never passed embeddings. Because the collection has an embedding function and we gave it text, Chroma computed the vectors for us. This is the moment the model download happens.

collection.query(query_texts=[...], n_results=2) embeds the question with the same model and returns the two nearest records. Notice that query_texts is a list, even for one question. Chroma can answer several questions in one call, and that shape explains the odd nesting of the output.

The result looks roughly like this (your distances will differ slightly by platform):

{
  'ids': [['a3', 'a1']],
  'documents': [['Refunds are issued to the original payment method within five days.',
                 'Your payment failed because the card was declined.']],
  'metadatas': [[{'topic': 'billing'}, {'topic': 'billing'}]],
  'distances': [[0.95, 1.21]],
  'embeddings': None, 'uris': None, 'data': None, 'included': [...]
}

Read it like this. Each key holds a list, and each of those holds one inner list per question you asked. We asked one question, so every outer list has one element, which is itself a list of two matches, best first. That is why you write results["documents"][0] to get the documents for your first question. The refund sentence ranks first, though it shares no important word with "I want my money back", which is the whole point of semantic search. The recipe about baking bread did not appear at all. Embeddings show as None because they are left out by default to keep responses small; you can ask for them explicitly.

Choosing a client: memory, disk or server

The client decides where your data lives, so choosing it is the first real design decision. Chroma offers four you will use as a beginner, and they all return the same kind of object with the same methods.

EphemeralClient() keeps data in memory. chromadb.Client() is equivalent. Use it for experiments, tests and notebooks where you want a clean slate each run.

PersistentClient(path="./chroma") stores data on disk in the folder you name. Run your script twice and the second run sees the first run's data. Write path explicitly. The official documentation text mentions a .chroma default, but in 1.5.9 the actual default is ./chroma, and relying on a default you cannot see is how people end up with several copies of a database in different working directories.

HttpClient(host="localhost", port=8000) connects to a Chroma server running elsewhere, which might be a second terminal on your own machine or another machine entirely. There is an AsyncHttpClient with the same arguments for asynchronous code. CloudClient() connects to Chroma Cloud, reading CHROMA_API_KEY, CHROMA_TENANT and CHROMA_DATABASE from the environment, but you do not need an account to learn Chroma, and it is not covered in this beginner guide beyond this mention.

Here is the same idea as a persistent script, which is the version most real projects start with:

import chromadb

client = chromadb.PersistentClient(path="./chroma")
collection = client.get_or_create_collection(name="help_centre")

print("records stored:", collection.count())

collection.upsert(
    ids=["a1"],
    documents=["Your payment failed because the card was declined."],
    metadatas=[{"topic": "billing"}],
)
print("records now:", collection.count())

Run it twice. The first run prints records stored: 0 then records now: 1. The second prints 1 and 1, because the data survived and upsert replaced the existing record instead of duplicating it. After running, look in your working directory: a chroma folder appeared, holding a SQLite file called chroma.sqlite3 plus index directories. That folder is your database. To back it up, stop your script and copy the whole folder.

Working with collections

Collections are the objects you create, find, list and delete. The calls are few, and each has one behaviour you should know.

col = client.create_collection(name="notes")          # fails if it exists
col = client.get_collection(name="notes")             # fails if it does not exist
col = client.get_or_create_collection(name="notes")   # the safe default for scripts
client.list_collections()                             # a list of Collection objects
client.count_collections()                            # how many exist
client.delete_collection(name="notes")                # irreversible
col.count()                                           # records in this collection
col.peek(limit=5)                                     # look at the first few records

create_collection raises an error if the name is taken: Collection [notes] already exists. get_collection raises Collection [notes] does not exist if it is missing. For scripts you run repeatedly, get_or_create_collection is the forgiving choice, but know its catch: if the collection already exists, any other arguments you pass, such as a new distance setting or new metadata, are ignored. It will not overwrite what is there.

You set the distance and a short description when you create a collection:

col = client.create_collection(
    name="notes",
    metadata={"description": "Course notes"},
    configuration={"hnsw": {"space": "cosine"}},
)

metadata here is a free-form note about the collection. configuration carries index settings, and {"hnsw": {"space": "cosine"}} chooses cosine distance. Remember that the space is fixed at creation. If you picked the wrong one, the fix is to create a new collection and add the data again, not to modify the old one.

list_collections() returns Collection objects, which is easy to forget because some old tutorials describe a version that returned only names. In 1.x you get objects, so print [c.name for c in client.list_collections()] when you only want names. It returns up to 100 by default, and you can pass limit and offset to page through more. peek is a quick way to see what is inside without writing a query, and count is how you check that a load worked.

You can rename a collection or change its metadata with col.modify(name="new-name", metadata={...}). And delete_collection is permanent, with no confirmation and no undo, so treat it as you would rm -r. If you are scripting cleanup, delete by exact name and print what you are about to delete first.

One more thing: when you attach your own embedding function, or choose to bring your own vectors, you say so at creation. Passing embedding_function=None creates a collection with no embedding function, which means you must supply embeddings yourself on every add and query. This is a legitimate pattern when you compute vectors elsewhere, and it explains one error you will see in the errors section.

Adding, updating and deleting records

Reading is the exciting part, but most bugs live in writing, because Chroma is forgiving in ways that hide mistakes. Learn the four write operations and their quirks.

col.add(ids=["n1", "n2"], documents=["first note", "second note"],
        metadatas=[{"week": 1}, {"week": 2}])

col.update(ids=["n1"], documents=["first note, edited"])

col.upsert(ids=["n2", "n3"], documents=["second note", "third note"],
           metadatas=[{"week": 2}, {"week": 3}])

col.delete(ids=["n3"])

add inserts new records. You must provide documents, embeddings, or both; metadata is optional. The ids must be strings, and they must be unique inside the call. The quirk that surprises everyone: adding an id that already exists is silently ignored. No error, no overwrite, and your new text is simply not stored. If you re-run a loading script and your edits never seem to take effect, this is why.

update changes records that already exist. If you pass new documents without embeddings, Chroma re-embeds them. Updating an id that does not exist does not raise; an error is logged and nothing changes, so check your ids if an update seems to vanish.

upsert means update-or-insert, and it is the right default for any script you will run more than once, because running it twice leaves the same result as running it once. That property has a name, idempotent, and it is worth wanting in every loading job you ever write.

delete removes records by id, or by a metadata filter such as col.delete(where={"week": 3}). Deleting by filter is powerful and easy to get wrong, so run the same filter through col.get(where=...) first to see what would go.

The rules about what you can store are strict, and breaking them produces errors you will meet in the next sections. Ids must be strings: 1 is rejected, "1" is fine. Metadata must be flat: values may be strings, integers, floats or booleans, or non-empty lists of those, but never a nested dictionary and never None in a call to add. If your data is nested, either flatten the keys, writing author_name rather than {"author": {"name": ...}}, or serialise the nested part to a JSON string. Lists of parallel inputs must be the same length, so three ids with two documents is an error.

Chroma also limits how many records you can send at once. Ask the client with client.get_max_batch_size(), which returns 5461 on a local 1.5.9 install; sending more raises Batch size 5462 exceeds maximum batch size 5461. For speed on larger loads, the documentation suggests batches in the range of 50 to 250 and sending several in parallel. For now, a simple loop that writes a few hundred records at a time is plenty.

Querying and getting: two ways to read

Chroma has two read operations, and picking the right one is a beginner skill. query ranks records by similarity to a question. get retrieves records by id or by a filter, with no ranking at all. Use query when you want what is closest in meaning, and get when you know exactly which records you want, or want to list everything that matches a condition.

# Ranked by meaning
res = col.query(
    query_texts=["how do I get a refund"],
    n_results=3,
    include=["documents", "metadatas", "distances"],
)

# Exact lookup, no ranking
one = col.get(ids=["n1"])
page = col.get(limit=10, offset=0, include=["documents"])

The n_results argument defaults to 10. If you ask for more results than the collection has, 1.5.9 simply returns everything it has with no error, but asking for zero is an error: Number of requested results 0, cannot be negative, or zero.

The include argument controls which fields come back. For query the default is documents, metadatas and distances. For get it is documents and metadatas. Valid values are documents, embeddings, metadatas, distances, uris and data. Ids are always returned and must not be listed. Writing include=["ids", ...] is a common mistake and produces Expected include item to be one of documents, embeddings, metadatas, distances, uris, data, got ids. Embeddings are left out by default because they are large; ask for them only when you need them, and in Python they arrive as NumPy arrays.

The two operations differ in the shape of their output, and mixing them up causes most beginner indexing errors. query handles a list of questions, so its results are nested: results["ids"][0] holds the ids for the first question. get has no questions, so its results are flat: one["ids"] is a plain list. Results are also column-major: instead of a list of record objects, you get one list of ids, one list of documents and so on, all in the same order. To walk through matches as rows, zip the columns together:

res = col.query(query_texts=["refund"], n_results=3)
for doc_id, doc, dist in zip(res["ids"][0], res["documents"][0], res["distances"][0]):
    print(f"{dist:.3f}  {doc_id}  {doc}")

One honest warning about search quality. Chroma returns the nearest records even when none of them is actually relevant. If you ask about quantum physics in a cooking collection, you still get results, just with large distances. A search with no good answer never comes back empty. In a real application you therefore look at the distances, and decide on a cut-off that suits your data and your model. Beginners often assume a result means a match; it only means "the least bad".

Filtering with where and where_document

Pure similarity is rarely enough. You often want "the closest passages, but only from the billing section" or "only from this year". Chroma lets you combine similarity with filters, and the filter runs together with the search rather than after it.

There are two filters. where filters on metadata. where_document filters on the text of the document itself. Both work on query, get and delete.

The shortest where is an equality test:

col.query(query_texts=["card problem"], n_results=3, where={"topic": "billing"})
col.get(where={"week": 2})

Beyond equality, where supports comparison and set operators, each written as a dictionary key beginning with a dollar sign:

col.get(where={"week": {"$gte": 2}})                       # greater than or equal
col.get(where={"topic": {"$in": ["billing", "account"]}})  # one of several values
col.get(where={"$and": [{"topic": "billing"}, {"week": {"$lt": 3}}]})
col.get(where={"$or": [{"topic": "billing"}, {"topic": "account"}]})

The full list is $eq, $ne, $gt, $gte, $lt, $lte, $in and $nin, plus $and and $or for combining conditions. There are also $contains and $not_contains for metadata values that are lists. A bare {"field": value} is shorthand for $eq. Two traps: an empty filter, where={}, is rejected with Expected where to have exactly one operator, got {}, so leave where out instead of passing an empty dictionary; and a typo such as $foo produces a clear error listing the valid operators.

where_document searches inside the text:

col.query(query_texts=["refund"], n_results=3,
          where_document={"$contains": "five days"})
col.get(where_document={"$regex": "^Refunds"})

It supports $contains, $not_contains, $regex and $not_regex, combined with $and and $or. Text matching here is case-sensitive, so "Refund" and "refund" are different. Use this filter for exact words, codes or phrases that a semantic search might blur; it is the beginner's version of combining keyword and meaning search.

How does a filter interact with ranking? Chroma applies the filter and ranks only within the records that pass. This means a very restrictive filter can leave fewer records than n_results, and then you simply get fewer results back. In rare, heavily filtered cases against a large index you may see the HNSW message Cannot return the results in a contiguous 2D array. Probably ef or M is too small; the first remedy is to ask for fewer results.

Running Chroma as a server and browsing your data

A persistent client is perfect until a second program needs the data. Then you want a server. Chroma's server is one command:

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

The startup banner prints Saving data to: ./chroma-data and Connect to Chroma at: http://localhost:8000. The chroma run command binds to localhost by default, so only your own machine can reach it; add --host 0.0.0.0 only when you truly intend other machines to connect, because, as the errors and security notes say, a 1.x server has no built-in authentication. The signature is chroma run [CONFIG_PATH] [--path <dir>] [--host localhost] [--port 8000], and you can supply a YAML configuration file instead of flags.

With the server running, check it from a second terminal:

curl http://localhost:8000/api/v2/heartbeat

You get back a JSON object with a nanosecond timestamp, which proves the server is alive. Note the /api/v2/ in the path. The older /api/v1/ endpoints were removed in 1.0 and now return HTTP 410 Gone with the message The v1 API is deprecated. Please use /v2 apis. If you ever see that, an old client or an old tutorial is talking to a new server.

Connect from Python with the HTTP client. Your add and query code is unchanged:

import chromadb

client = chromadb.HttpClient(host="localhost", port=8000)
print(client.heartbeat())            # an integer, nanoseconds

col = client.get_or_create_collection(name="help_centre")
col.upsert(ids=["a1"], documents=["Your payment failed."], metadatas=[{"topic": "billing"}])
print(col.query(query_texts=["card problem"], n_results=1)["documents"][0])

If the server is not running you get ValueError: Could not connect to a Chroma server. Are you sure it is running?. The first checks are always the same: is the server process alive, is the port right, and, with Docker, did you publish the port?

Docker is the most common way to run a server you want to leave running:

docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma:1.5.9

The -v flag mounts a folder at /data, which is where the container stores its database, and -p 8000:8000 publishes the port. Since 1.0, the data path inside the container is /data; older guides that mount /chroma/chroma are out of date, and following them silently stores your data inside the disposable container. If you are new to containers, the Docker guide explains images, volumes and ports from scratch.

Finally, you can look at your data in a browser interface. The command-line tool includes chroma browse:

chroma browse help_centre --local
chroma browse help_centre --path ./chroma

Pointing it at a collection lets you scroll records and see metadata, which beats printing dictionaries when you are checking whether a load worked. The same tool offers chroma install --list for sample apps, chroma update to upgrade the command-line tool, and chroma docs to open the documentation.

Bringing your own embeddings and choosing an embedding function

So far Chroma has computed every vector with its default model. Two other patterns come up quickly, and both are one argument away.

The first is choosing a different embedding function. Chroma ships wrappers in chromadb.utils.embedding_functions for many providers. For example, with OpenAI:

from chromadb.utils import embedding_functions

ef = embedding_functions.OpenAIEmbeddingFunction(model_name="text-embedding-3-small")
col = client.create_collection(name="docs_openai", embedding_function=ef)

This reads your key from the OPENAI_API_KEY environment variable; if your key lives under another name, pass api_key_env_var="MY_VAR". Never paste a key into source code. There are wrappers for Cohere, Google, Hugging Face, Ollama, Mistral, Jina, Voyage and others, and a local option, SentenceTransformerEmbeddingFunction, that runs a model on your own machine. Pick a provider based on cost, language coverage and privacy. For Arabic content in particular, test a multilingual model against your own sentences before committing, because a small English-centred model may rank Arabic text poorly. The default model is mainly trained on English, and you should verify it on your data rather than assume.

The second pattern is supplying embeddings yourself, which you do when you compute vectors in another system:

col = client.create_collection(name="external", embedding_function=None)
col.add(
    ids=["e1", "e2"],
    embeddings=[[0.1, 0.2, 0.3], [0.2, 0.1, 0.4]],
    documents=["first", "second"],
)
print(col.query(query_embeddings=[[0.1, 0.2, 0.35]], n_results=1)["ids"])

Chroma stores the vectors exactly as given and never re-embeds them. Note the dimension: the first add fixed it at three, so a later query with a two-number vector raises Collection expecting embedding with dimension of 3, got 2. And on a collection created with embedding_function=None, calling query(query_texts=...) fails with You must provide an embedding function to compute embeddings, because there is nothing to turn the text into numbers. Either pass query_embeddings or attach a function.

Once a collection has an embedding function, Chroma remembers its configuration, so get_collection later rebuilds it without you passing it again, provided the client and server are at least version 1.1. What it cannot remember is your secret key. When you move a script to a new machine, set the environment variable there too. If you change the embedding model for a collection that already has data, the old vectors no longer match the new ones. The only correct fix is a new collection and a full reload.

Configuration, settings and housekeeping

Most beginners never need to touch configuration, but you should know what exists so that you can recognise it when it appears in other people's code.

Per-collection configuration controls the index. The common keys sit under hnsw: space (the distance), ef_construction, ef_search, max_neighbors, resize_factor, sync_threshold, num_threads and batch_size. The 1.5.9 defaults include space of l2, ef_construction of 100, ef_search of 100 and max_neighbors of 16. As a beginner, set only space, and leave the rest alone. Two are creation-only: the space and ef_construction cannot change afterwards. Trying to change the space with modify produces unknown field space, expected one of ef_search, max_neighbors, num_threads, resize_factor, sync_threshold, batch_size. The remedy is a new collection.

Server configuration comes from command-line flags, a YAML file, or environment variables. The ones worth recognising are CHROMA_PERSIST_PATH (where data lives), CHROMA_PORT (default 8000), CHROMA_LISTEN_ADDRESS and CHROMA_ALLOW_RESET. Nested keys use a double underscore, as in CHROMA_OPEN_TELEMETRY__ENDPOINT. If you find an old tutorial using variables such as CHROMA_SERVER_AUTHN_PROVIDER, ignore it: built-in authentication no longer exists.

Resetting is deliberately hard. client.reset() deletes everything, so it is disabled by default and raises Reset is disabled by config. For experiments you can enable it with Settings(allow_reset=True) in your own process, or allow_reset: true on a server. Never enable it anywhere that holds data you care about.

Housekeeping. There is no built-in backup command for a single node. To back up, stop the server (or snapshot the volume) and copy the whole data folder, which holds chroma.sqlite3 and the index directories. There is also chroma vacuum --path <dir>, which compacts the SQLite file and is needed once if you upgrade a database created before version 0.5.6; it blocks reads and writes, so stop the server first. A note for readers of the official docs: their vacuum page shows chroma utils vacuum, but on 1.5.9 that fails with unrecognized subcommand 'utils'; the working form is chroma vacuum.

Common errors and how to read them

Chroma's errors are usually specific, which is a gift. Read the whole message; it generally names the exact value that was wrong. Here are the ones you will meet, grouped by what you were doing.

Creating and finding collections. Collection [demo] already exists means create_collection hit a name that is taken; use get_or_create_collection. Collection [nope] does not exist means the opposite: check the spelling, and check that you are connected to the right client, since an ephemeral client and a persistent client have different contents. Validation error: name: Expected a name containing 3-512 characters from [a-zA-Z0-9._-]... means the name broke the naming rules, often because it was too short.

Writing. Expected ID to be a str, got 1 means you used a number as an id; wrap it in str(). Unequal lengths for fields: ids: 2, embeddings: 1 means your parallel lists do not line up. Expected IDs to be unique, found duplicates of: z in add means one batch contained the same id twice. Expected metadata value to be a str, int, float, bool, SparseVector, list, or None, got {...} which is a dict means nested metadata. Expected metadata list value for key 't' to be non-empty means an empty list in metadata. A None metadata value on a local add produces Cannot convert Python object to MetadataValue; drop keys that are None. And Batch size 5462 exceeds maximum batch size 5461 means chunk your writes. Remember also the silent cases: adding an existing id and updating a missing id raise nothing.

Dimensions. Collection expecting embedding with dimension of 3, got 2 is almost always a mixed-model problem: your stored vectors came from one model and your query vectors from another. Use the same embedding function for both, and when you change models, make a new collection. Non-finite float value at embedding index 0: NaN means a vector contains a not-a-number; clean your data before sending it.

Querying. Number of requested results 0, cannot be negative, or zero means n_results=0. The include error about got ids means you listed ids in include. The where errors, empty filter or unknown operator, were covered earlier. You must provide an embedding function to compute embeddings means you called query_texts on a collection with no embedding function.

Connecting. Could not connect to a Chroma server means the server is down, the port is wrong, or Docker's -p is missing. Tenant [nope] not found and Database [nope] not found mean you passed names that do not exist; the defaults are default_tenant and default_database. An HTTP 410 on /api/v1 means an old client against a 1.x server; upgrade the client.

Putting it all together

Let us finish with one small end-to-end project that uses everything: a command-line tool that loads a text file of notes into a persistent collection and answers questions from it. It is deliberately short, but it is the real shape of a retrieval pipeline.

Create notes.txt with one note per line, then kb.py:

import sys
import chromadb

client = chromadb.PersistentClient(path="./chroma")
col = client.get_or_create_collection(
    name="notes",
    configuration={"hnsw": {"space": "cosine"}},
)


def load(path: str) -> None:
    with open(path, encoding="utf-8") as f:
        lines = [line.strip() for line in f if line.strip()]
    col.upsert(
        ids=[f"note-{i}" for i in range(len(lines))],
        documents=lines,
        metadatas=[{"source": path, "line": i} for i in range(len(lines))],
    )
    print(f"loaded {len(lines)} notes, collection has {col.count()}")


def ask(question: str) -> None:
    res = col.query(query_texts=[question], n_results=3)
    for doc, dist in zip(res["documents"][0], res["distances"][0]):
        print(f"{dist:.3f}  {doc}")


if __name__ == "__main__":
    command, argument = sys.argv[1], sys.argv[2]
    load(argument) if command == "load" else ask(argument)

Use it like this:

python kb.py load notes.txt
python kb.py ask "how do I get my money back"

Walk through the design choices, because each one comes from earlier in this guide. It uses a persistent client so the data survives between commands. It uses get_or_create_collection so the script is safe to run repeatedly, and cosine distance, set once at creation. It loads with upsert and stable ids built from the line number, so re-running load never duplicates records. It stores metadata about where each note came from, so that later you can filter by source or show a citation. And it prints the distances next to each answer, so you can see how confident the match is.

To turn this into the retrieval half of a question-answering system, take the top documents from ask, put them in a prompt as context, and send that prompt to a language model; the LangChain guide and the LlamaIndex guide show frameworks that wrap exactly this pattern, and the Claude API guide covers the model call. If you would rather compare Chroma with other stores before choosing, the Qdrant guide and the pgvector guide cover two common alternatives.

One real-world limit to plan for early: a note long enough to contain several ideas gets one embedding that blurs them all together. Real systems chunk long documents into passages of a few sentences each before adding them. Keep each record about one idea, and your retrieval improves more than any setting change will.

What you can now do, and what comes next

You started with a database that finds text by meaning, and you can now use it for real. You can explain what an embedding is and why lower distance means a better match. You know the nouns, tenant, database, collection and record, and which ones you will touch at first. You can install and pin Chroma 1.5.9 and verify it. You can create ephemeral, persistent and server-backed clients and choose between them. You can add, update, upsert, delete, query and get, read the nested results, filter with where and where_document, supply your own vectors, run chroma run or Docker, and read the errors that come back.

Just as important, you know the quiet traps: adding an existing id does nothing, the distance is fixed at creation, a query always returns something, mixing embedding models breaks dimensions, and a self-hosted 1.x server has no login of its own.

What comes next in the mid-level guide: how to tune and measure retrieval quality, filter in depth, set HNSW parameters, write a custom embedding function, batch and parallelise loads, run with a configuration file, and test code that depends on Chroma. The senior guide covers architecture, sizing memory for the index, multi-tenancy, securing and upgrading a server, backups, observability, and when to choose something other than Chroma.

Practise before moving on. The best exercise is the one in the last section with your own data, because retrieval quality depends on your text far more than on any setting.

Sources

• Chroma documentation home
• Introduction
• Getting started
• Migration notes
• Troubleshooting
• Clients
• Client-server mode
• Manage collections
• Configure collections
• Add data
• Update data
• Delete data
• Query and get
• Metadata filtering
• Full-text search
• Embedding functions
• CLI: run
• CLI: browse
• CLI: vacuum
• Docker deployment
• Server environment variables
• Architecture overview
• Chroma releases on GitHub
• chromadb on PyPI

Part one of three. A twenty-five-minute review of the Beginner Detailed track, then the questions interviewers ask about Chroma. Mid-level reviews this plus its own material; Senior reviews all three. Everything here refers to Chroma 1.5.9.

The thirty-second answer

Chroma is an open-source database for retrieval. You store documents with their embeddings, which are vectors produced by a model so that similar meanings land close together, plus metadata. Later you query with text, and Chroma returns the nearest records, optionally narrowed by metadata or text filters. It runs embedded in your Python process, as a single server, or as a managed distributed service.

Then the line that shows you have used it: "a query always returns the nearest records even when none is relevant, so I look at the distances, and a lower distance means a closer match."

The model

The three deployment modes

Commands and calls to have ready

pip install "chromadb==1.5.9"
chroma --version
chroma run --path ./chroma-data --port 8000
curl http://localhost:8000/api/v2/heartbeat
chroma browse my_collection --path ./chroma
docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma:1.5.9

client = chromadb.PersistentClient(path="./chroma")
col = client.get_or_create_collection(name="docs", configuration={"hnsw": {"space": "cosine"}})
col.upsert(ids=["a"], documents=["text"], metadatas=[{"k": 1}])
col.query(query_texts=["question"], n_results=3, where={"k": 1})
col.get(ids=["a"])
col.delete(ids=["a"])

An interviewer will often ask you to write a short ingest and query snippet on a whiteboard. Practise it until you can produce it without looking, including the nested result shape, results["documents"][0].

The classic traps and why they happen

Adding an existing id does nothing. add silently ignores ids that already exist, because Chroma treats add as insert-only. The symptom is edits that never appear. Use upsert.

The distance is fixed at creation. The index is built around one distance function, so space and ef_construction cannot be changed on a live collection. Changing them means a new collection and a full reload.

Mixed embedding models. Stored vectors and query vectors must come from the same model. A mismatch of dimension raises Collection expecting embedding with dimension of 3, got 2. A mismatch between two models with the same dimension raises nothing and returns poor results, which is worse.

A query never comes back empty. It returns the nearest records, however far away. Without a distance cut-off you can feed irrelevant text to a language model.

Results are nested. query takes a list of questions, so its output is a list of lists. get is flat.

No built-in authentication. Chroma 1.0 removed it. A self-hosted port is open to anyone who can reach it.

The persistent path. The 1.5.9 default for PersistentClient is ./chroma, relative to the working directory, so running a script from a different folder creates a second database. Always pass path.

The server version looks wrong. A 1.5.9 server reports "1.0.0" on /api/v2/version, because that is the API version.

Common interview questions

What is an embedding, and why does retrieval use them?

An embedding is a vector of floating-point numbers produced by a model from some input, arranged so that inputs with similar meaning get nearby vectors. Retrieval uses them because keyword search misses synonyms and paraphrase: "my card was declined" and "payment failed" share no words but sit close together in vector space. So retrieval becomes a nearest-neighbour search: embed the question, find the closest stored vectors, return their documents.

A strong answer adds that the model matters, that the same model must embed documents and queries, and that quality depends on the model's language coverage, which matters for Arabic content.

What does Chroma store for each record?

A required string id unique within the collection, an embedding, an optional document string, optional flat metadata with string, integer, float or boolean values or non-empty lists of those, and an optional uri. You can supply documents and let Chroma embed them, supply embeddings yourself, or both.

What is a collection, and how does it relate to a database and tenant?

A collection is the unit of storage and querying, indexed independently, with a name of 3 to 512 characters from letters, digits, dots, underscores and hyphens. Collections live inside a database, which lives inside a tenant. Defaults are default_database and default_tenant. On a self-hosted server these are namespaces rather than a security boundary, since there is no built-in authentication.

What is the difference between query and get?

query ranks records by similarity to your input and returns the top n_results, 10 by default. get fetches by id or by a metadata or document filter, with optional limit and offset, and does no ranking. Use query for "closest in meaning" and get for "exactly these records" or "list everything that matches".

How do you read the output of query?

It is column-major and nested per question. results["ids"][0], results["documents"][0], results["distances"][0] and results["metadatas"][0] are parallel lists for the first question, ordered best first. I zip them to iterate as rows. Embeddings are excluded unless requested through include.

Which distance should I use, and how do I read it?

The options are l2 (the default, squared Euclidean), cosine and ip. For text embeddings cosine is the usual convention, because it compares direction rather than length. For all three, lower distance means more similar, so the best match has the smallest number. The distance is set at creation with configuration={"hnsw": {"space": "cosine"}} and cannot be modified afterwards.

Why does re-running my loading script not update my documents?

Because I used add, and add silently ignores ids that already exist. The fix is upsert, which inserts new ids and replaces existing ones, making the script idempotent. update also replaces, but it ignores ids that do not exist, logging an error without raising.

What are the options for the embedding function, and what is the default?

By default, a collection uses all-MiniLM-L6-v2 from Sentence Transformers, run locally through ONNX, producing 384-dimensional vectors, downloaded to ~/.cache/chroma/onnx_models on first use. You can attach providers such as OpenAI, Cohere, Google, Hugging Face, Ollama, Mistral, Jina or Voyage, or pass embedding_function=None and supply vectors yourself. Since version 1.1 the embedding function configuration is saved with the collection, but API keys are not, so every process needs the environment variable.

How would you filter results by metadata?

Pass where to query, get or delete. where={"topic": "billing"} is equality. Operators include $eq, $ne, $gt, $gte, $lt, $lte, $in and $nin, with $and and $or to combine conditions. For text inside the document, where_document supports $contains and $regex, case-sensitively. An empty where={} is rejected.

What is the difference between an ephemeral, a persistent and an HTTP client?

Ephemeral keeps everything in memory and loses it when the process ends. Persistent writes to a folder you name, so data survives restarts, but it belongs to one process. The HTTP client connects to a server started with chroma run or Docker, so several programs can share one dataset. The calls for adding and querying are identical across all three.

How do you run Chroma in Docker, and what changed in 1.0?

docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma:1.5.9. The data path inside the container is /data; before 1.0 it was /chroma/chroma, and an old mount path would leave data in the container's disposable layer. Pin the image tag rather than using latest.

Is a self-hosted Chroma server secure by default?

No. Since 1.0 there is no built-in authentication or authorisation, so anyone who can reach the port has full control, including deleting collections. I would keep it on a private network or behind a proxy that enforces authentication and TLS, and keep allow_reset disabled.

Your query returns results, but they look irrelevant. What do you check?

First the distances: a large distance means the nearest record is still far away, and I would add a threshold. Then I would check that the same embedding function was used at add and query time, that the documents are chunked into single-idea passages, that the distance space suits the model, and that the language of the content is covered by the embedding model. Finally I would test a handful of known question and answer pairs to measure rather than guess.

Why did my script create a second empty database?

Probably the PersistentClient was created without an explicit path or run from a different working directory, so it used a new ./chroma. I pass an absolute or clearly relative path, and check col.count() on startup.

What does get_or_create_collection do if the collection exists?

It returns the existing collection, and any other arguments, such as new metadata or configuration, are ignored. It does not overwrite.

What is HNSW?

Hierarchical navigable small world: a graph-based index that finds approximate nearest neighbours without comparing against every vector. It is much faster than a full scan and slightly approximate, and in local and single-node Chroma it must fit in memory.

Can you use Chroma without an internet connection?

Yes, once the default model is cached or if you supply your own embeddings. The first use of the default embedding function downloads the model, so a machine with no access, or with a TLS-inspecting proxy that its Python does not trust, fails on the first add with a certificate error. The fix is to trust the proxy's certificate or copy the cached model across.

Where does Chroma sit in a RAG system?

It is the retrieval layer. You embed and store chunks of your documents, embed the user's question, fetch the nearest chunks, and insert them in the prompt as context for a language model. Chroma does not generate answers. Related guides are LangChain, LlamaIndex and RAGAS for measuring retrieval quality.

When would you pick something other than Chroma?

When data outgrows one machine's memory and you cannot use the managed service, when you need built-in authentication and access control without a proxy, or when your data already lives in Postgres and pgvector would avoid a second system. Others to compare are Qdrant, Pinecone, Weaviate and Milvus. A good answer names the trade-off rather than a winner.

Why does Chroma limit how many records you can write in one call?

A single request has a maximum batch size, which client.get_max_batch_size() reports as 5461 on a local 1.5.9 install. Exceeding it raises Batch size 5462 exceeds maximum batch size 5461. In practice I chunk loads into batches of a few hundred, because the documentation suggests 50 to 250 per batch with several sent in parallel for throughput.

How do you check that a load actually worked?

I compare col.count() with the number of input records, look at a few with col.peek(limit=5) or chroma browse, and run two or three known questions through query to confirm the right records come back. Counting alone is not enough, because a silently ignored duplicate id leaves the count short without any error.

What is the safest way to change the embedding model on an existing collection?

Do not change it in place. Create a new collection with the new embedding function, reload every source document, run the evaluation questions against both, and switch the application only when the new one is at least as good. The old vectors are tied to the old model.

What a strong answer covers that a weak one misses

A weak answer defines Chroma as "a vector database" and stops. A strong answer explains the problem it solves (semantic similarity beyond keywords), names the objects (collection, record, embedding function, distance), and reaches for the traps without being asked: upsert versus add, the fixed distance, the single embedding model, the absence of authentication, and the nested result shape. It also shows measurement habits, such as checking distances and keeping a small set of test questions.

Interviewers also listen for honesty about limits. Saying "local Chroma is for prototypes and moderate workloads, and some features such as the Search API are Cloud only" lands better than overclaiming. If you do not know a detail, say how you would check it, for instance help(chromadb.PersistentClient) or the version-specific documentation, instead of guessing.

Scenario prompts to rehearse out loud

Rehearse these aloud, in about a minute each.

"Build a search over our FAQ in an afternoon." Persistent client with an explicit path, one collection with cosine distance, one record per answer with a stable id and a topic in the metadata, upsert to load, query with n_results=3, print distances, and test with ten real questions before showing anyone.

"The team wants two services to share the data." Move from the persistent client to a server: chroma run or the pinned Docker image with a mounted /data, both services using HttpClient, the server on a private network with a proxy for authentication, and a note about a backup of the data folder.

"Search quality dropped after we changed the model." The old vectors came from the old model. Create a new collection with the new embedding function, reload every document, compare against the test questions, then switch the application over. Do not mix models in one collection.

"Someone deleted a collection." There is no undo and no built-in backup command on a single node. Restore from a copy of the data folder or snapshot, and then discuss network restrictions and the absence of built-in authorisation to prevent a repeat.

Sixty-second self-test

Answer aloud, without looking up.

1. What are an embedding, a document, a record and a collection?
2. Which distance does Chroma use by default, and does a higher or lower number mean a better match?
3. What happens if you add an id that already exists?
4. Why can't you change a collection's distance after creating it?
5. What is the shape of query output for one question, and how do you reach the documents?
6. What is the difference between query and get?
7. What does where={} do?
8. Name the three client types and when you would pick each.
9. What does a 1.5.9 server say its version is, and why?
10. Does a self-hosted Chroma 1.x server authenticate users?

If you hesitated on more than two, reread the matching section of the detailed guide and run its Try it task again.

Part one of three. Most Chroma problems at this level come from a few causes: you assumed a write operation would complain and it stayed silent, you mixed two embedding models, or you forgot where your data actually lives. Start with the table, then the longer explanations, then the habits and the checklist. Everything here refers to Chroma 1.5.9.

Common errors at this level

The mistakes beginners actually make

1. Using add in a script you run twice

Symptom. You edit a sentence in your source file, run the loader again, and the old sentence still comes back from queries. The count never changes either.

Cause. add is insert-only. When an id already exists, Chroma ignores the new record without raising an error. The design avoids accidental overwrites, but it hides your intent.

Fix. Use upsert for any loader that may run more than once. Pair it with stable ids, for instance faq-refunds-001, or a hash of the source text, so the same input always lands on the same record. Check the result with col.get(ids=[...]) rather than assuming.

2. Mixing embedding models

Symptom. Either an error about dimensions, or, more dangerously, no error and bad results.

Cause. A vector only means something relative to the model that produced it. A collection created with the default 384-dimension model and queried with vectors from a 1536-dimension model raises the dimension error. Two models that happen to share a dimension raise nothing, and similarity becomes meaningless.

Fix. Treat the model as part of the collection's identity. Put the model name in the collection metadata, for example metadata={"model": "all-MiniLM-L6-v2"}, so a colleague can see it. When you change models, create a new collection, reload everything, evaluate it, then switch. Do not try to patch the old collection.

3. Trusting the first result

Symptom. Your chatbot confidently answers from a passage that has nothing to do with the question.

Cause. A query returns the nearest records regardless of how near they are. A cooking collection asked about tax still returns three recipes.

Fix. Request distances (they are on by default) and look at them. Compare the distances of questions you know are answerable against questions you know are not, and choose a cut-off from that evidence. When nothing passes the cut-off, say so instead of passing weak text to a language model. Remember that lower is better, and that the numbers depend on the distance space, so a threshold from l2 does not carry over to cosine.

4. Misreading the nested output

Symptom. TypeError, or printing a whole list where you expected a string.

Cause. query accepts a list of questions and returns a list per question. results["documents"] is a list of lists.

Fix. Index with [0] for the first question, and zip the columns:

res = col.query(query_texts=["refund"], n_results=3)
for i, doc, dist in zip(res["ids"][0], res["documents"][0], res["distances"][0]):
    print(f"{dist:.3f} {i} {doc}")

get has no questions, so its output is flat. Mixing the two shapes is the most common beginner type error.

5. Picking the wrong distance and finding out late

Symptom. Rankings feel slightly off, and you want to switch to cosine after loading a hundred thousand records.

Cause. The default space is l2, and the distance is fixed when the collection is created. modify rejects it with unknown field space.

Fix. Decide before loading. For text, set configuration={"hnsw": {"space": "cosine"}} at creation, unless your model's documentation says otherwise. If you got it wrong, build a new collection from your source data. This is the main reason to keep the original documents outside Chroma, in files or a database, so a rebuild is a script rather than a crisis.

6. Losing data to the wrong client or folder

Symptom. "My data disappeared." The count is zero, or the collection does not exist.

Cause. One of three things. You used EphemeralClient, which forgets everything. You used a relative PersistentClient path and ran from a different directory, so a new folder was created. Or you ran a Docker container without a volume, so the data lived in a disposable layer; and since 1.0 the container path is /data, so a mount of the older /chroma/chroma path persists nothing.

Fix. Always pass path explicitly. At the top of a script, print col.count(). In Docker, use -v ./chroma-data:/data, then stop and remove the container and start a new one to prove that the data survives.

7. Exposing the server

Symptom. None, until someone deletes a collection, or a security review.

Cause. A 1.x self-hosted server has no built-in authentication, and containers listen on all interfaces by default. chroma run itself binds to localhost, but --host 0.0.0.0 and Docker publishing change that.

Fix. Keep the port on a private network or behind a reverse proxy that enforces authentication and TLS. Do not follow old tutorials that set CHROMA_SERVER_AUTHN_PROVIDER; those settings belong to versions before 1.0. Where you run the server also decides where your data physically sits, which matters when your employer has data-residency rules.

8. Stuffing long documents into one record

Symptom. Results are vague. A long contract matches almost everything, a little.

Cause. One embedding has to represent the whole text, so several ideas blur together, and returning the whole document is useless as context anyway.

Fix. Split long text into chunks of a few sentences, one idea each, and store the source and position in metadata so you can trace a chunk back. Chunking usually improves retrieval more than any index setting.

9. Assuming an English model handles Arabic

Symptom. Arabic questions return irrelevant Arabic passages, while English questions work.

Cause. The default model is small and primarily trained on English. Coverage of other languages is weaker.

Fix. Try a multilingual embedding model, wired in through an embedding function, and compare both on twenty real questions. The result depends on your data, so measure it rather than trust a general claim.

10. Hitting the first-run download in the wrong place

Symptom. The very first add pauses for a long time, fails with a certificate error, or fails with no network at all, perhaps in CI or a container build.

Cause. The default embedding function downloads its model to ~/.cache/chroma/onnx_models the first time it is needed. A corporate TLS proxy or a restricted network blocks it.

Fix. Run once on a connected machine and copy the cache folder, or trust your company's root certificate through SSL_CERT_FILE. Never disable certificate verification. In CI, cache that folder between runs so every job does not download again.

11. Calling a Cloud-only feature locally

Symptom. NotImplementedError: Search is not implemented for Local Chroma, or the same for fork.

Cause. The Search API with Search, Knn and Rrf, and collection forking, are Chroma Cloud features. Tutorials often show them without saying so.

Fix. On local and single-node installs, use query and get. Read the docs page header to see whether a feature is Cloud-only before copying it.

12. Using stale documentation

Symptom. A command from the docs fails, or a tutorial's settings do nothing.

Cause. Chroma changed a lot between 0.4, 0.5, 0.6 and 1.0, and the documentation is not perfect. Two examples: the vacuum page shows chroma utils vacuum, which fails on 1.5.9 with unrecognized subcommand 'utils', and the working command is chroma vacuum --path <dir>; and the page on conditional transactions describes a feature that is not in 1.5.9.

Fix. Check the version in the tutorial against yours, prefer the current 1.x pages, and test small. When something fails, run chroma --help or help(...) in Python to see what your installed version actually offers.

Habits worth adopting on day one

Pin the version. Write chromadb==1.5.9 in your requirements file and the same tag in your Docker command. Chroma moves quickly, and a client and server on different minor lines are an avoidable source of confusion. The JavaScript package is numbered separately, so check which one a tutorial means.

Keep your source documents elsewhere. Chroma is an index, not the system of record. Keep the original files or database rows, so that changing a model, a distance or a chunk size is a rebuild script. People who treat the vector store as the only copy end up afraid of every change.

Write idempotent loaders. Stable ids plus upsert means a failed job can simply be re-run.

Decide metadata up front. A filter can only use fields you stored. Source, section, date and language are cheap to add at load time and expensive to add later.

Look at your data. Use col.peek(limit=5), col.count(), and chroma browse my_collection --path ./chroma. Reading a few real records catches empty strings, truncated text and wrong metadata before they become retrieval bugs.

Keep a tiny evaluation set. Ten or twenty questions, each with the record that should come back. Run them after any change of model, distance or chunk size, and note how many land at rank one and in the top three. It takes an hour to build and it replaces opinions with numbers. When you want to go further, the RAGAS guide shows how to measure retrieval and answer quality at scale.

Read the whole error. Chroma's messages name the offending value, such as the dimension, the id or the operator. They usually answer the question you were about to type into a search engine.

Choose the client deliberately. Ephemeral for tests and experiments, persistent for a single program, HTTP when several programs share data. Switching later changes one line.

Protect the data folder. The folder holds chroma.sqlite3 and the index directories. Back up by stopping the process or snapshotting the volume and copying the whole folder, never a single file. Run backups before upgrades.

Use environment variables for keys. Embedding providers read keys such as OPENAI_API_KEY. Keep them out of source control, and remember that Chroma saves the embedding function configuration but never the key, so every machine needs its own.

Run it in a container early. Starting from a pinned image with a mounted /data folder teaches you the volume habit while the stakes are low. The Docker guide covers the volume and port basics.

Practice cards

Card 1: the idempotent loader. Write a function that reads a text file and loads one record per line with upsert and ids derived from the line content. Run it twice and prove the count did not change. Edit one line, run it again, and confirm the old text did not stay behind as a duplicate. Hint: think about what happens to the id if it comes from the content.

Card 2: the threshold. Load twenty sentences on one topic. Write five questions you know are answerable and five that are not. Print the best distance for each. Where would you put the cut-off, and how many questions would it get wrong?

Card 3: the model swap. Create two collections from the same sentences, one with the default model and one with another embedding function. Run the same ten questions against both and count first-rank hits. Which won, and was the difference larger than your noise?

Card 4: break it on purpose. Trigger these four errors and write the cause of each: a duplicate collection name, a numeric id, a wrong-dimension query vector, and an empty where.

Card 5: the server round trip. Start chroma run --path ./chroma-data, load data through HttpClient, stop the server, start it again, and confirm that the data is still there. Then try curl against the heartbeat endpoint and against /api/v1/heartbeat, and explain the difference in the responses.

Card 6: filters. Store records with a topic and a numeric year. Write one query using $and, one using $in, and one using where_document with $contains. Which of the three is case-sensitive?

Quick references

A few shapes to keep nearby.

# Create once, reuse forever
col = client.get_or_create_collection(
    name="docs",
    metadata={"model": "all-MiniLM-L6-v2"},
    configuration={"hnsw": {"space": "cosine"}},
)

# Safe write
col.upsert(ids=ids, documents=docs, metadatas=metas)

# Ranked read with a filter
res = col.query(query_texts=[q], n_results=5, where={"topic": "billing"})

# Exact read
rows = col.get(where={"year": {"$gte": 2024}}, limit=20, include=["documents", "metadatas"])

When you cannot remember the argument names, the client signatures in 1.5.9 are PersistentClient(path=...), HttpClient(host="localhost", port=8000), and EphemeralClient(). The default query size is 10 results. Ids come back without being asked for, and embeddings come back only when requested. The maximum batch size on a local install is 5461.

A short checklist

Before you call a Chroma project done, tick each of these.

• The version is pinned, both in the Python requirements and, if used, in the Docker tag.
• The client type is deliberate, and a persistent path is explicit.
• The collection name follows the rules, and the distance space was chosen before loading.
• The collection metadata records which embedding model was used.
• The loader uses upsert with stable ids and is safe to run twice.
• Metadata is flat, with no None values, and contains the fields you will filter on.
• Long documents are chunked into single-idea records.
• Queries print distances, and the application has a cut-off for weak matches.
• A small set of test questions measures retrieval quality.
• Keys come from environment variables, never from source files.
• The original documents are kept outside Chroma, so a rebuild is cheap.
• The data folder or volume has a tested backup.
• A server, if you run one, is not reachable from the public internet and sits behind authentication.
• You know that the server reporting "1.0.0" is normal.

Tick all fourteen and you are using Chroma in a way that will survive the move from the beginner to the mid-level track.

This is part two of three. It picks up where Beginner ended and takes the everyday Chroma calls you already make a little further, then adds the machinery that decides whether a retrieval service stays fast, correct and safe once real users depend on it. Everything here is written against Chroma 1.5.9, the current stable release of the Python package, and where the official docs and the shipped package disagree we say so and follow the package.

Where this picks up

Each section starts with the problem it solves and ends, where it helps, with a Try it you can run against a scratch directory in a few minutes.

How a single-node Chroma stores and serves data

Beginner treated Chroma as a place to put vectors and get neighbours back. To operate it you need a more precise picture, because every performance and durability behaviour follows from it.

Chroma has five core components, and they are the same whether you run in a notebook or on a cluster. A gateway validates requests and enforces auth, rate limits and quotas. A log, the write-ahead log or WAL, durably records every write before it is acknowledged. A query executor answers vector, full-text and metadata queries and consults the log so that a read sees recent writes. A compactor turns the log into index versions in the background. A system database, the sysdb, is the catalogue of tenants, databases and collections.

In single-node mode, which covers both PersistentClient and chroma run, those roles are folded into one process and the storage is simple. A SQLite file named chroma.sqlite3 holds metadata, documents and the WAL. Alongside it, under the same directory, Chroma keeps an HNSW index per collection. HNSW, hierarchical navigable small world, is the approximate nearest neighbour index Chroma uses locally. It is a graph of vectors that lets a query hop towards its neighbours instead of comparing against every vector, and it is built in memory.

That last sentence is the one to remember. The HNSW index must fit in RAM. Disk holds the durable copy, but a query runs against the in-memory graph. When the data outgrows memory you do not get gracefully slower queries, you get an unhappy process. We turn this into numbers in the sizing section.

Two consequences follow from the single-directory layout. First, the whole database is one directory, so backing up and moving it is a file operation, provided nothing is writing while you copy. Second, because writes land in the WAL first and the index catches up, there is a window between "write acknowledged" and "write visible in the index". Chroma hides this from local queries by consulting the log, which is why add followed immediately by query finds your record.

The data model sits above the files. A tenant is the top-level unit, a database is a namespace inside a tenant, and a collection lives in a database. By default you are in default_tenant and default_database. A collection name must be 3 to 512 characters from a-z A-Z 0-9 . _ -, start and end with an alphanumeric, contain no .., and not look like an IP address. A name that breaks the rule fails with InvalidArgumentError: Validation error: name: Expected a name containing 3-512 characters ..., and a one-letter name is the commonest way to trigger it.

Picking the client and the deployment mode

The client you choose is really a decision about where the work happens, and getting it wrong creates the most common architecture problem in Chroma projects: several application replicas each opening the same on-disk database.

PersistentClient(path=...) runs the whole engine inside your Python process. It is perfect for notebooks, scripts, tests and single-process tools. It is wrong for a web service with more than one worker or replica, because each process would be its own database engine over the same files, with no coordination. The moment you have more than one process that needs to read or write, run a server and talk to it with HttpClient.

chroma run or the Docker image gives you a single-node server. The architecture documentation positions single-node for small to medium workloads, typically fewer than ten million records across a handful of collections. Beyond that you are in distributed territory, which means Chroma Cloud or a self-run distributed deployment.

A detail that matters at this level is the thin client. pip install chromadb-client gives you an HTTP-only client with a much smaller footprint. It has no default embedding function and no local engine, so it suits an application container that only talks to a server. Install it instead of chromadb, not alongside it. This keeps your API image small and keeps the ONNX model machinery out of services that never embed locally.

Use the async client when your application is already async. await chromadb.AsyncHttpClient(host="localhost", port=8000) takes the same arguments as the sync client, and it avoids blocking your event loop on network calls.

Pin your versions. The server image, chromadb/chroma:1.5.9, and the client package should sit on the same minor line, and you should never deploy latest. There is a subtle trap here: the GitHub release labelled "latest" is a development build from the main branch, with a version such as 1.5.10.dev..., not a stable release. Pin the stable number from PyPI.

Another trap is the default path. The docs text mentions .chroma, but the 1.5.9 signature is PersistentClient(path='./chroma', ...), and chroma run also defaults to ./chroma. Always pass the path explicitly so that the data location is a line you can find in code review, not an accident of the working directory.

Embedding functions: what is persisted and what is not

At Beginner level the embedding function, or EF, was something that happened automatically. At work it is the part of the system that most often goes quietly wrong, because it spans your code, the server, a model and, often, a paid API.

An EF turns text, or images, into vectors. Chroma attaches one to a collection, and add, update, upsert and query call it when you pass documents or query_texts instead of vectors. The default is all-MiniLM-L6-v2, a 384-dimension Sentence Transformers model run through ONNX. On first use Python downloads it to ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2.

Since Chroma 1.1 the EF's configuration is stored with the collection. That is why client.get_collection(name="docs") works without you passing the EF again, and why a second service connecting to the same collection embeds queries the same way as the one that ingested. The configuration is the model name and the settings, not secrets. An OpenAI EF's configuration records the model and the name of the environment variable it reads, never the key. So every client process still needs OPENAI_API_KEY, or whichever variable you named, in its own environment.

If your environment variable has a non-standard name, say so when you build the EF:

import chromadb
from chromadb.utils import embedding_functions

ef = embedding_functions.OpenAIEmbeddingFunction(
    model_name="text-embedding-3-small",
    api_key_env_var="MYCO_OPENAI_KEY",
)
client = chromadb.HttpClient(host="localhost", port=8000)
col = client.get_or_create_collection(name="support-articles", embedding_function=ef)

The rule that follows is blunt: one collection, one embedding model, forever. The first record fixes the dimension. Add with a 384-dimension model and later query with a 1536-dimension one and you get InvalidArgumentError: Collection expecting embedding with dimension of 384, got 1536. That error is the lucky outcome. If two different models happen to share a dimension, nothing fails and every result is quietly meaningless, because the vectors live in different spaces. Changing models always means a new collection and a full re-ingest.

You can opt out of an EF entirely by passing embedding_function=None and supplying your own vectors with embeddings=. Do that when embedding happens elsewhere, for example in a batch job on GPUs. The price is that query_texts stops working, and you get You must provide an embedding function to compute embeddings if you try it.

Writing your own

A custom EF is a small class, but in current Chroma it needs more than __call__ if you want it to survive being persisted and rebuilt by another client:

from chromadb import Documents, EmbeddingFunction, Embeddings
from chromadb.utils.embedding_functions import register_embedding_function


@register_embedding_function
class InternalGatewayEF(EmbeddingFunction):
    def __init__(self, model: str):
        self.model = model

    def __call__(self, input: Documents) -> Embeddings:
        # call your internal embedding service here and return a list of vectors
        ...

    @staticmethod
    def name() -> str:
        return "internal-gateway"

    def get_config(self):
        return {"model": self.model}

    @staticmethod
    def build_from_config(config):
        return InternalGatewayEF(config["model"])

The argument must be named input. A signature using texts is the pre-0.4.16 form and fails validation. name, get_config and build_from_config are what let the server record the EF and another process rebuild it. Without them it still works in the process that created the collection and surprises everyone else.

For Gulf and Egyptian teams there is a practical point: an EF that calls a public API sends every document to that provider, so if policy keeps data in region, use a self-hosted model or the local ONNX default. Behind a TLS-inspecting proxy the default model download fails with [SSL: CERTIFICATE_VERIFY_FAILED]; trust the proxy CA through SSL_CERT_FILE or REQUESTS_CA_BUNDLE, or pre-populate ~/.cache/chroma/onnx_models.

Distance spaces and HNSW tuning

A distance space defines what "near" means, and you pick it exactly once. Chroma supports three. l2 is squared Euclidean distance and is the default. cosine is one minus cosine similarity. ip is one minus the dot product. In all three, a smaller number means more similar, so a distance of zero is an identical match under cosine, and a value near 1 means unrelated.

Choose the space your embedding model was trained for. Most text embedding models are designed around cosine similarity, and many produce normalised vectors for which cosine and inner product rank identically. If you never set the space you silently get l2, which is why teams migrating from other vector stores see different scores for the same data. Set it explicitly:

col = client.create_collection(
    name="support-articles",
    configuration={"hnsw": {"space": "cosine", "ef_construction": 200, "max_neighbors": 32}},
)

Both the space and ef_construction are creation-only. Try to change the space later with col.modify(configuration={"hnsw": {"space": "l2"}}) and 1.5.9 raises unknown field 'space', expected one of 'ef_search', 'max_neighbors', 'num_threads', 'resize_factor', 'sync_threshold', 'batch_size'. That message is useful, because it lists exactly what you may change after the fact.

The defaults verified on 1.5.9 are ef_construction=100, ef_search=100, max_neighbors=16, resize_factor=1.2 and sync_threshold=1000. Here is what each does, so that tuning is a decision and not a guess.

• max_neighbors is how many links each graph node keeps. More links give better recall and a larger, slower-to-build index. Treat it as fixed at creation, as the docs do.
• ef_construction is how wide the search is while building the graph. Higher values build a better graph more slowly. Creation only.
• ef_search is how wide the search is at query time. It is the main recall-versus-latency dial and, usefully, you can change it on a live collection. Raise it when recall disappoints, lower it when latency does.
• num_threads controls parallelism and defaults to the CPU count.
• sync_threshold and batch_size control how writes are batched into the index and persisted.

One HNSW error is worth recognising: Cannot return the results in a contiguous 2D array. Probably ef or M is too small. It appears when a query asks for more neighbours than the graph can produce, which is typical under very restrictive filters. Lower n_results, or raise ef_search.

Filtering with where and where_document

Metadata filtering is where Chroma earns its keep over a bare vector index, and also where subtle behaviour hides. There are two filters. where filters on metadata. where_document filters on the document text. They combine, and they apply to query, get and delete.

The metadata operators are $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, $not_contains, plus the logical $and and $or, which take lists. A bare {"field": value} is shorthand for $eq. Document operators are $contains, $not_contains, $regex, $not_regex, $and and $or.

results = col.query(
    query_texts=["how do I reset my password"],
    n_results=5,
    where={"$and": [
        {"lang": {"$eq": "en"}},
        {"updated_year": {"$gte": 2024}},
        {"product": {"$in": ["portal", "mobile"]}},
    ]},
    where_document={"$not_contains": "deprecated"},
    include=["documents", "metadatas", "distances"],
)

Several behaviours here surprise people who learned filtering elsewhere.

Empty filters are rejected. where={} fails with Expected where to have exactly one operator, got {}. Code that builds filters dynamically must omit the argument when there are no conditions, not pass an empty dict. Likewise a single-key dict is fine, but a dict with two keys at the top level is not: wrap conditions in $and.

Negative operators match missing keys. Since 0.5.12, $ne and $nin also match records that lack the key altogether, and $not_contains on a document matches records with no document. A filter such as {"status": {"$ne": "archived"}} therefore returns records that never had a status. That is usually what you want, but not always, so test it.

Full-text matching is case-sensitive. $contains: "Refund" will not match "refund". If case matters to your users, normalise at ingestion into a lowercase metadata field and filter on that.

Metadata is flat. Values are strings, integers, floats, booleans, or non-empty arrays of one of those types. Nested dicts fail with Expected metadata value to be a str, int, float, bool, SparseVector, list, or None, got {'a': 1} which is a dict. An empty list fails too, and a None value inside add fails with a TypeError about converting to MetadataValue. So build your metadata with a small helper that drops None, flattens nested keys with dots, and omits empty arrays.

Arrays give you tags. Store {"genres": ["action", "drama"]} and filter with {"genres": {"$contains": "action"}}. The value you pass to $contains must be a scalar of the element type. The array must be homogeneous and not nested.

Filtering has a cost that vector-only thinking misses. A filter is applied alongside the graph search, so a filter that excludes nearly everything can leave the search with too few candidates. This is the situation behind the contiguous-array error above. If a particular filter value is very selective, for example one customer in a million, consider a separate collection per customer instead of a metadata filter.

One more tool is the ids argument to query, which restricts the candidate set to a list of IDs. It is handy for re-ranking a shortlist you already have.

Writing data safely at volume

Beginner showed add. At scale the interesting questions are about what add refuses to do, and the answers are mostly silent.

Adding an ID that already exists is ignored. No error, no warning, and the old record stays unchanged. If your ingestion job re-runs after a document edit and uses add, the edit never lands and nothing tells you. Use upsert, which inserts or overwrites. Updating an ID that does not exist is also ignored, though an error is logged. This is why an ingestion pipeline should be built on upsert with deterministic IDs.

A deterministic ID derives from the content's identity, not from a counter or a random UUID. For a document split into chunks, f"{doc_id}:{chunk_index}" is stable across runs, so re-ingesting a changed document overwrites its chunks. Be aware of the leftover problem: if the new version has fewer chunks than the old one, the surplus old chunks remain. Delete by metadata before re-ingesting:

def reingest(col, doc_id, chunks, base_meta):
    col.delete(where={"doc_id": doc_id})
    col.upsert(
        ids=[f"{doc_id}:{i}" for i in range(len(chunks))],
        documents=chunks,
        metadatas=[{**base_meta, "doc_id": doc_id, "chunk": i} for i in range(len(chunks))],
    )

IDs must be strings. Passing an integer fails with Expected ID to be a str, got 1. Duplicate IDs inside a single call fail with DuplicateIDError: Expected IDs to be unique, found duplicates of: z in add. Lists of different lengths fail with Unequal lengths for fields. NaN or infinite values in a vector are rejected with Non-finite float value. These loud errors are the good ones. Prefer them to the silent ones.

Batching has a hard limit and a soft target. The hard limit is the server's maximum batch size, which client.get_max_batch_size() reports and which is 5461 on a local 1.5.9. Exceed it and you get Batch size 5462 exceeds maximum batch size 5461. The documented recommendation for throughput is smaller batches, 50 to 250 records, with several writers in parallel. A simple ingestion loop:

from concurrent.futures import ThreadPoolExecutor

def batches(items, size=200):
    for i in range(0, len(items), size):
        yield items[i:i + size]

def write(batch):
    col.upsert(
        ids=[r["id"] for r in batch],
        documents=[r["text"] for r in batch],
        metadatas=[r["meta"] for r in batch],
    )

with ThreadPoolExecutor(max_workers=4) as pool:
    list(pool.map(write, batches(records)))

Wrapping the map in list is deliberate: it forces exceptions in worker threads to surface instead of vanishing.

When you embed with an API, the cost is in the embedding calls, not in Chroma. Batch the texts you send to the provider, respect its rate limits, and consider computing embeddings outside Chroma and passing embeddings= so that retries do not re-bill you for text you already embedded.

Running a server you can defend

A development server and a production server differ in configuration and, more importantly, in what surrounds them. The single most important fact about self-hosted Chroma 1.x is this: it has no built-in authentication or authorisation. The 1.0 rewrite removed the old providers. Environment variables such as CHROMA_SERVER_AUTHN_PROVIDER and CHROMA_SERVER_AUTHZ_CONFIG still appear in older tutorials and are listed as historical. Setting them on a 1.x server does not protect anything.

So anyone who can reach the port can read every collection and call delete_collection. Your defences are structural:

• Keep the server on a private network, with no public IP and tight security groups or firewall rules.
• Put a reverse proxy or API gateway in front that terminates TLS and checks credentials, whether that is OIDC, mutual TLS or a static token check, and have clients send the credential as a header with HttpClient(headers={...}).
• Leave allow_reset at its default of false, so that client.reset() fails with Reset is disabled by config.
• Set cors_allow_origins to explicit origins, not ["*"], if a browser ever talks to it. Better, never let a browser talk to it directly.

Note the bind address: chroma run listens on localhost unless you pass --host, whereas the Docker image and the config default to 0.0.0.0. A container exposed with -p 8000:8000 on a public interface is therefore open to the world, and publishing the port only on a private interface is a deliberate choice you make.

Run it in Docker with the data path as /data, which changed from /chroma/chroma in 1.0:

services:
  chroma:
    image: chromadb/chroma:1.5.9
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - chroma-data:/data
      - ./chroma-config.yaml:/config.yaml:ro
    restart: unless-stopped

volumes:
  chroma-data:

Mounting a file at /config.yaml supplies a custom server configuration. The official fully annotated example uses these keys, and the ones that matter in production are below.

port: 8000
listen_address: "0.0.0.0"
max_payload_size_bytes: 41943040
cors_allow_origins: ["https://app.example.com"]
persist_path: "/data"
allow_reset: false
sqlitedb:
  hash_type: "sha256"
  migration_mode: "validate"
open_telemetry:
  service_name: "chroma"
  endpoint: "http://otel-collector:4317"

Most of these also have environment-variable forms, with a double underscore for nested keys: CHROMA_PERSIST_PATH, CHROMA_PORT, CHROMA_LISTEN_ADDRESS, CHROMA_MAX_PAYLOAD_SIZE_BYTES, CHROMA_CORS_ALLOW_ORIGINS, CHROMA_SQLITEDB__MIGRATION_MODE, CHROMA_SQLITEDB__HASH_TYPE and CHROMA_OPEN_TELEMETRY__ENDPOINT. Prefer the file for anything you want reviewed in version control, and use environment variables for values that differ per environment.

migration_mode: validate is a production habit worth adopting. With the default apply, a server upgraded to a newer image migrates the SQLite schema on startup. With validate it refuses to start when a migration is needed, so schema changes happen when you decide, with a backup taken first. If you are new to containers, the Docker guide covers volumes, health checks and restart policies in the depth this section assumes.

Provider keys follow the same rule as always: from a secret manager into the environment of the process that embeds, never into the image or the repository. If you use Chroma Cloud, the CLI writes a .env file for you with chroma db connect <name> --env-file. Treat that file as a secret and keep it out of version control.

Capacity planning and sizing

Because the HNSW index lives in memory, capacity planning for single-node Chroma is mostly arithmetic about RAM, and the official performance guide gives you the formula. For vectors of 1024 dimensions, with about three metadata fields and small documents, the number of embeddings you can hold is roughly N = R x 0.245, where N is millions of embeddings and R is gigabytes of RAM. Keep at least a gigabyte for the operating system, and do not deploy on less than 2 GB.

The published benchmark table is a good sanity check:

Treat these as a starting point. Your dimension, metadata volume and document size shift the curve. A 384-dimension model uses far less memory per vector than a 1536-dimension one, so the model you choose is also a capacity decision. Disk should be at least RAM plus several gigabytes, because the SQLite file and index directories both grow.

Splitting data across collections neither helps nor hurts single-node performance as long as everything fits in memory, so organise collections for clarity and lifecycle, not speed. On distributed Chroma and Cloud the advice reverses: sharding by tenant into separate collections helps, because each collection has isolated cold-start behaviour and rate limits.

Health, observability and the server's own telemetry

A vector database is infrastructure, so it needs the same visibility as one. What Chroma gives you is narrower than a database with a metrics endpoint, and it helps to know exactly what is and is not there.

For health, the server exposes /api/v2/heartbeat, /api/v2/pre-flight-checks and /api/v2/version. Use the heartbeat as a liveness probe. It returns a nanosecond timestamp as JSON, and HttpClient.heartbeat() returns the same as an integer. Remember that the version endpoint reports the API version, not the package, and returns "1.0.0" on a 1.5.9 server.

For deeper visibility, the server exports OpenTelemetry traces. The documentation describes traces only, and no built-in metrics endpoint is documented for single-node. Point it at a collector with CHROMA_OPEN_TELEMETRY__ENDPOINT, set the service name with CHROMA_OPEN_TELEMETRY__SERVICE_NAME, and pass collector headers through OTEL_EXPORTER_OTLP_HEADERS if your backend needs them. The YAML open_telemetry block also supports per-crate filters with a level, which lets you raise detail for one component. The official observability example runs Chroma with the OpenTelemetry Collector and Zipkin, and you generate a first trace by calling the heartbeat. The OpenTelemetry guide explains collectors and exporters.

Because the server gives you few metrics, measure from the client: log embed time, search time, result count and best and worst distance per request.

import logging, time

log = logging.getLogger("retrieval")

def retrieve(col, text, n=5, where=None):
    t0 = time.perf_counter()
    kwargs = {"query_texts": [text], "n_results": n, "include": ["documents", "metadatas", "distances"]}
    if where:
        kwargs["where"] = where
    res = col.query(**kwargs)
    d = res["distances"][0]
    log.info("retrieval ms=%.0f hits=%d best=%.3f worst=%.3f filtered=%s",
             1000 * (time.perf_counter() - t0), len(d), d[0] if d else -1, d[-1] if d else -1, bool(where))
    return res

For application-level tracing of the whole retrieval-augmented pipeline, the docs list integrations with OpenLLMetry, OpenLIT, Braintrust and DeepEval, and the catalogue's Langfuse guide covers a tool that records retrieval spans alongside model calls.

Telemetry in the other direction deserves a clear statement, because security reviewers ask. As of 1.5.4 Chroma no longer collects product telemetry. The anonymized_telemetry setting still exists for compatibility and does nothing.

Backups, upgrades and migrations

Single-node Chroma has no built-in backup command. That is not as bad as it sounds, because the entire state is one directory, but it means that backup is your job and that it needs the right moment.

The rule is that a copy is only trustworthy when nothing is writing. Either stop the server and copy the whole persist directory, including chroma.sqlite3 and the index directories, or take a volume-level snapshot that is atomic at the storage layer. Copying a live SQLite file with cp can produce a file that does not open. Schedule backups, store them off the machine, and, most importantly, test a restore into a scratch server by starting it on the copy and querying it.

docker compose stop chroma
tar -czf chroma-$(date +%F).tgz -C /var/lib/docker/volumes/myproj_chroma-data/_data .
docker compose start chroma

The CLI can also move data. chroma copy copies collections between a local instance and Chroma Cloud, with --from-local or --from-cloud selecting the direction. It is a migration aid more than a backup strategy.

Upgrades follow a short ritual:

1. Read the release notes for every minor line between your version and the target.
2. Take a backup and verify it restores.
3. Upgrade the server image and the client package together, and keep them on the same minor line.
4. With migration_mode: validate set, expect the server to refuse a start that needs a schema migration. Switch to apply for the one upgrade, then back.
5. Run your retrieval tests, which we describe in the next section, against the upgraded server before routing traffic to it.

Some historical details still catch teams with old data. A database created before 0.5.6 needs chroma vacuum --path <dir> once, which blocks reads and writes, so stop the server first. The official vacuum page says chroma utils vacuum, but on 1.5.9 that fails with unrecognized subcommand 'utils', and the working command is chroma vacuum --path <dir>, with optional --force and --timeout. Data from before 0.4, created with the old DuckDB or ClickHouse backends, needs the separate chroma-migrate tool. And a pre-1.0 container mounted its volume at /chroma/chroma, so a compose file carried over from then must be changed to /data or the server will start on an empty directory and look as though your data is gone.

Changing the embedding model, the dimension or the space is not an upgrade, it is a migration. The pattern is blue-green: create a new collection with the new settings, re-ingest from source, point a configuration value at the new name, verify, and only then delete the old collection. Keep the collection name in configuration, for example support-articles-v2, so that the switch is a deploy and not a code change.

Tenants, databases and what they do not protect

Chroma's hierarchy of tenant, database and collection looks like a multi-tenancy feature, and for namespacing it is. Be precise about what it does on a self-hosted server.

AdminClient creates and manages the namespaces: create_tenant, create_database, get_database, delete_database and list_databases. A normal client scopes itself with tenant= and database= in its constructor, or by calling set_tenant and set_database. Collection names are unique within a database, so two databases can each have a collection called docs.

import chromadb

# A client scoped to one tenant and database, as created through AdminClient
client = chromadb.HttpClient(host="localhost", port=8000, tenant="team-search", database="prod")

The point to carry away is the security boundary. With no built-in auth on self-hosted Chroma, these names are labels. A client that knows another tenant's name can pass it and read the data. The hierarchy gives you organisation, not isolation. If different customers must not see each other's data, enforce it in a layer you control: a proxy that maps an authenticated identity to a fixed tenant and database and rewrites or rejects anything else, or your own API that never exposes Chroma to callers at all.

Choose the isolation shape deliberately. There are three patterns.

• One collection per customer. Strong logical separation, simple deletion of a customer's data, no risk of a missing filter leaking results. On single-node it costs little. On distributed Chroma and Cloud it is the recommended pattern, and Cloud allows up to a million collections.
• One collection, a tenant_id metadata field. Fewer objects to manage, but every query must carry the filter, and one forgotten where leaks data between customers. If you choose this, centralise the query function so that the filter cannot be omitted, and test it.
• One database per environment. Use databases to separate dev, staging and prod data in one server, and not for customers.

Testing retrieval

Most teams test their prompts and never test their retrieval, then discover that bad answers began with bad context. Retrieval is deterministic enough to test properly, and Chroma makes that cheap.

There are three layers, from fast to slow.

Unit tests with an ephemeral client. chromadb.EphemeralClient() is in-memory and starts instantly, so each test can build its own collection from a handful of documents and assert on filtering and ID behaviour. Use a fresh collection name per test, since the in-process client can share state within a process. The goal at this layer is your own code: the metadata helper that drops None, the filter builder that omits empty conditions, the re-ingest function that deletes stale chunks.

import chromadb, pytest, uuid

@pytest.fixture
def col():
    client = chromadb.EphemeralClient()
    return client.create_collection(
        name=f"t-{uuid.uuid4().hex[:12]}",
        embedding_function=None,
        configuration={"hnsw": {"space": "cosine"}},
    )

def test_upsert_overwrites(col):
    col.upsert(ids=["a"], embeddings=[[1.0, 0.0]], documents=["one"])
    col.upsert(ids=["a"], embeddings=[[1.0, 0.0]], documents=["two"])
    assert col.get(ids=["a"])["documents"] == ["two"]

def test_add_does_not_overwrite(col):
    col.add(ids=["a"], embeddings=[[1.0, 0.0]], documents=["one"])
    col.add(ids=["a"], embeddings=[[1.0, 0.0]], documents=["two"])
    assert col.get(ids=["a"])["documents"] == ["one"]

Passing hand-written vectors with embedding_function=None makes these tests offline, fast and deterministic. It also avoids the ONNX download, which is a real benefit in CI behind a TLS-inspecting proxy.

Evaluation sets. For retrieval quality you need questions with known right answers. Write 30 to 100 realistic questions, each with the IDs of the chunks that should be retrieved. Then compute hit rate at k, the share of questions whose right chunk appears in the top k, and mean reciprocal rank, which rewards putting it first. Run this against the real embedding model and the real data, record the numbers, and fail the build if they fall below a threshold. Every change to chunking, the embedding model, the space or ef_search is then a measurable experiment instead of an opinion. The RAGAS guide goes further, scoring whole answers on faithfulness and context relevance.

def hit_rate_at_k(col, cases, k=5):
    hits = 0
    for question, expected_ids in cases:
        got = col.query(query_texts=[question], n_results=k)["ids"][0]
        hits += any(i in got for i in expected_ids)
    return hits / len(cases)

Integration tests against a real server. Start the pinned Docker image in CI, run the same suite through HttpClient, and include the failure paths: a wrong dimension, a bad collection name, an oversized batch. This layer catches the things an ephemeral client cannot, such as proxy header handling, payload limits and version drift between client and server.

Debugging beyond the basics

The exact error messages are the best debugging tool Chroma gives you, so learn to read them as a diagnosis. Here are the ones you will meet at work and what each really says.

Collection [demo] already exists means create_collection ran twice. Use get_or_create_collection, and remember that for an existing collection it ignores the extra arguments, including metadata. A change to metadata or configuration you thought you made did not happen. Collection [nope] does not exist usually means the name is right but the tenant or database is wrong, so check those before the spelling. Tenant [x] not found and Database [x] not found say the same thing more directly.

Could not connect to a Chroma server. Are you sure it is running? is a networking error, not a Chroma error. Check, in order: that the process is up, the port, whether Docker published it, and the bind address. A server started with chroma run and no --host listens on localhost only, so a client on another machine cannot reach it even though the server is healthy.

A 410 with The v1 API is deprecated. Please use /v2 apis means an old client, or a script using raw /api/v1 calls, is talking to a 1.x server. Upgrade the client.

If results look wrong with no error, work down this list.

1. Wrong distances? Check the space. The default l2 is not cosine, so scores differ from tutorials written against other stores.
2. Empty results? Check the filter. Print it. A where on a key that does not exist matches nothing, and a case-mismatched $contains matches nothing.
3. Embeddings are None? They are excluded by default. Add "embeddings" to include. They come back as NumPy arrays, so compare with numpy, not ==.
4. Irrelevant hits? Look at the distances. If the best one is large, the corpus lacks an answer and you need a threshold. If it is small but the text is wrong, the chunks or the embedding model are at fault.
5. Fewer hits than n_results? If n_results exceeds the collection size you simply get everything, with no error.
6. Query and ingest disagree? Compare col.configuration_json for the embedding function and the space, and confirm both services see the same collection through get_collection_by_id, available since 1.5.7.

The CLI helps too. chroma browse <collection> --local opens a terminal browser over local data, so you can look at the records themselves, which is often the quickest way to notice that chunks are truncated or metadata is missing. The official guide titled "Look at your data" makes the same point, and it is the most underused debugging step in retrieval systems.

If a failure comes from the wrapper library rather than Chroma, reproduce it with the bare client first. LangChain and LlamaIndex add their own defaults, such as their own collection names, so a bug that exists only through the wrapper is a configuration issue in the wrapper.

What is Cloud only, and what to call "not yet released"

A lot of Chroma documentation describes capabilities that do not exist on the server you are running. The official open-source page says plainly that most engineering effort goes to distributed Chroma and Chroma Cloud, and that local Chroma may temporarily lack features. Learn the boundary now, so that you do not design around something you cannot run.

Features that exist on Chroma Cloud and distributed Chroma but not on a local or single-node 1.5.9 server:

• The Search API, with Search, K, Knn and Rrf, which supports hybrid dense and sparse ranking with rank fusion. Calling col.search(...) locally raises NotImplementedError: Search is not implemented for Local Chroma, or over HTTP, Search operation is not implemented for local executor. On Cloud it replaced query as the recommended path, though query and get stay supported there.
• Schema-driven index control, including sparse vector indexes for BM25 or SPLADE, and customer-managed encryption keys.
• Collection forking, a copy-on-write clone that is near-instant, which locally raises Collection forking is not implemented for Local Chroma.
• The SPANN index. Local Chroma uses HNSW, and SPANN's parameters are not user-tunable.

There is one more category, which is documentation ahead of the release. The docs describe conditional transactions, collection.conditional() with commit and retry, but on 1.5.9 hasattr(collection, "conditional") is False. It is on the main branch and not in the stable package. Do not build on it, and if you read it in a tutorial, treat it as upcoming.

Integrating with frameworks and the neighbouring stack

Most teams meet Chroma through a framework. That is fine, as long as you know where the framework stops and Chroma starts.

LangChain ships a separate package, langchain-chroma, with from langchain_chroma import Chroma. You give it a collection name, an embedding object from LangChain, and either a persist directory or a client, so passing your own HttpClient is the way to point it at a server. Metadata filters pass through as Chroma where dictionaries. LlamaIndex has llama-index-vector-stores-chroma, which wraps a Chroma collection as a vector store. Both wrap their own embedding classes, which means the embedding model is configured in the framework and not in Chroma. If you also call the collection directly, you must make sure both paths use the same model, which is the single most common integration bug.

The sensible approach is to let the framework do ingestion and chains, but own the connection. Create the Chroma client and collection yourself, with the space and configuration you chose, and hand the existing collection to the framework. That way the HNSW settings, naming and tenant stay under your control. See the LangChain and LlamaIndex guides for the framework side.

Serving. A retrieval endpoint is usually a small web service. In FastAPI, create the HttpClient once at startup and reuse it, validate the incoming filter against an allowlist of metadata fields so callers cannot construct arbitrary where clauses, and return only the fields the caller needs. Because the Chroma server has no auth, this service is the trust boundary.

Kubernetes. For a single-node server, a StatefulSet with one replica and a persistent volume mounted at /data is the shape. Do not scale it above one replica, since each replica would be a separate database. Set a memory limit comfortably above your computed index size, use the heartbeat for probes, and add a NetworkPolicy so that only your retrieval service can reach the port. The Kubernetes guide and Helm guide cover those objects. Distributed Chroma has Helm templates in the repository, but Cloud is the supported way to run the distributed system.

Putting it all together

Here is a compact but production-shaped design, using everything above. It is a support-article retrieval service.

The data is a few thousand help articles in English and Arabic, owned by one company. Sizing first: roughly 40,000 chunks at 768 dimensions is far below one million vectors, so a 4 GB instance holds it with room to grow, and single-node Chroma is appropriate. The embedding model is chosen for multilingual text, and the choice is recorded in the collection name: support-multilingual-v1. The space is set to cosine at creation, and ef_construction and max_neighbors are set then too, because they cannot change.

Chroma runs from the pinned image chromadb/chroma:1.5.9 on a private subnet, with its volume mounted at /data, a mounted config file with migration_mode: validate, allow_reset: false, and OpenTelemetry pointed at the collector. Nothing outside the retrieval service can reach its port. The retrieval service, a FastAPI application, holds the only HttpClient, authenticates callers itself, allows filtering only on lang, product and updated_year, and logs the embed time, search time and best and worst distance for each request.

Ingestion is a scheduled job that hashes each article, skips unchanged ones, and replaces the chunks of changed ones with deterministic IDs. Quality is guarded by an evaluation set run in CI, and operations are rehearsed: nightly backups, a monthly restore test, and the upgrade ritual from earlier. Changing the embedding model means a new versioned collection and a configuration swap.

import os
import chromadb

COLLECTION = os.environ["CHROMA_COLLECTION"]          # e.g. support-multilingual-v1

client = chromadb.HttpClient(
    host=os.environ["CHROMA_HOST"],
    port=int(os.environ.get("CHROMA_PORT", "8000")),
    headers={"Authorization": f"Bearer {os.environ['CHROMA_PROXY_TOKEN']}"},
)
collection = client.get_or_create_collection(
    name=COLLECTION,
    configuration={"hnsw": {"space": "cosine", "ef_construction": 200, "max_neighbors": 32}},
)

Notice what the sketch does not do. It does not rely on Chroma for authentication, it does not let a wrapper pick the space, and it does not treat any silent behaviour as an error signal. Each choice traces back to a behaviour covered in this guide.

Where you are now

You can now reason about Chroma, not just call it. You know that single-node storage is SQLite plus an in-memory HNSW index, that the index must fit in RAM, and how to size a machine from that. You know why one persistent directory belongs to one process, and when to run a server instead. You choose a distance space once and deliberately, and you know which HNSW settings you can still change afterwards. You write ingestion that is safe to re-run, and you know which operations fail silently. You can read the exact error messages of 1.5.9 as diagnoses.

You also know the limits. Self-hosted 1.x has no built-in auth, so the proxy or service in front of it is your security. Tenants and databases are namespaces, not walls. Backups are your responsibility and a restore is the only proof of one. And you can tell the local features from the Cloud-only and the not-yet-released ones.

The next level, Senior, treats Chroma as a platform other teams depend on: the failure modes of the distributed architecture, the Cloud Search API and Schema in depth, security and supply chain, cost control, governance, and the honest question of when to choose something else. Before you go, make sure your retrieval has an evaluation set, your backups have a tested restore, and your versions are pinned.

Sources

• Chroma documentation home
• Architecture overview
• Clients
• Client-server mode
• Manage collections
• Configure collections
• Add data
• Delete data
• Query and get
• Metadata filtering
• Full-text search
• Embedding functions
• Chunking guide
• Docker deployment
• Observability
• Single-node performance
• Server environment variables
• Migration notes
• Troubleshooting
• Open-source overview
• Vacuum command
• Chroma Cloud pricing
• Chroma Cloud quotas and limits
• Cloud Search API overview
• LangChain integration
• LlamaIndex integration
• Chroma MCP server
• Chroma releases on GitHub
• chromadb on PyPI

This is part two of three, the mid-level interview file. At this level an interviewer is no longer asking what a collection is. They describe a situation, usually a failing or slow retrieval system, and watch how you reason. Answers here are written against Chroma 1.5.9. A strong answer names the mechanism, says what it would check first, and states the trade-off. Each section below gives the question, a model answer, and what separates a strong answer from a weak one.

How these interviews work

Mid-level questions come in three shapes. Scenario questions give you symptoms, such as wrong results, slow queries or data that vanished, and expect an ordered investigation. Trade-off questions ask you to choose between two reasonable options and defend the choice. Depth probes start from something you said and keep asking why until you reach the mechanism.

A habit that helps in all three: separate what you know from what you would check. "I would look at the distances first, because they tell me whether the corpus has an answer at all" is better than a confident guess, and it shows how you work. Interviewers also notice when you name the version. Saying "on 1.5.9 that is silently ignored" shows you have run it, not just read about it.

Scenario: results are irrelevant but nothing errors

The question. "Users say the assistant's answers are wrong. You log the retrieved chunks and they look unrelated to the question. Chroma returns results with no errors. Where do you start?"

A strong answer. I treat it as a retrieval problem until proven otherwise, and I narrow it by layers, starting with the cheapest check.

First, look at the distances, not only the text. If the best distance is large, the corpus probably does not contain an answer, and the fix is a distance threshold and an honest "I do not know" path. If the best distance is small but the text is irrelevant, something is wrong with the vectors themselves.

Second, check that query and ingestion used the same embedding model. A dimension mismatch fails loudly, with Collection expecting embedding with dimension of 384, got 1536. The dangerous case is two models with the same dimension, which fails silently and returns nonsense. I would read the collection's configuration and compare the embedding function it recorded to what the query service is using.

Third, check the distance space. If nobody set it, the collection is l2, the default, but the embedding model may be built for cosine. Results are still ranked, just less well, and since the space cannot be changed after creation the fix is a new collection.

Fourth, check the filter. A where that is too narrow returns the few records that survive it, even when they are poor matches. Print the filter actually sent.

Fifth, look at the chunks. Use chroma browse or peek and read ten records. Truncated text, boilerplate navigation, or chunks that cut sentences in half are common and invisible from code.

What separates strong from weak. A weak answer jumps to "use a better model" or "increase n_results". A strong answer checks distances, model consistency, space, filter and data in that order, and mentions that a silent same-dimension model mismatch exists. Bonus points for proposing an evaluation set so the investigation becomes a measurable experiment.

Scenario: ingestion reruns but edits never appear

The question. "A nightly job reloads help articles into Chroma. Editors changed an article yesterday, but search still shows the old text. The job reports success."

A strong answer. That is the signature of add on an existing ID. In Chroma, adding an ID that already exists is ignored, without an error, and the stored record stays as it was. A job that uses add with stable IDs therefore succeeds every night while changing nothing. The fix is upsert, which inserts or overwrites.

The same applies in reverse: update on an ID that does not exist is also ignored, with an error logged but nothing raised, so a pipeline that assumes update creates records will lose data quietly.

Then I would think one step further, about stale chunks. If the edited article now splits into fewer chunks, an upsert overwrites the first chunks but leaves the old extra ones in place, so deleted paragraphs keep surfacing. I would delete by a doc_id metadata filter before upserting, or track chunk counts. I would also add a content hash in metadata to skip unchanged documents, which saves embedding cost.

Finally, I would add a test that ingests a document, edits it, re-ingests, and reads the record back, because this class of bug is invisible in logs.

What separates strong from weak. Weak answers blame caching or the embedding model. Strong answers know the silent-ignore behaviour, propose deterministic IDs and upsert, and notice the stale-chunk follow-on problem.

Scenario: queries slow down as the data grows

The question. "Retrieval was fast at launch. Six months and a few million records later, latency is poor and the server sometimes restarts. What do you suspect?"

A strong answer. Single-node Chroma keeps the HNSW index in memory, so I would suspect memory first. The official sizing guidance gives a rule of thumb for 1024-dimension vectors, about 0.245 million embeddings per gigabyte of RAM, with at least a gigabyte kept for the operating system. If the index has outgrown the container's memory limit, the process can be killed and restarted, which looks like intermittent latency and "random" restarts. I would check the container's memory against restart events.

Before changing anything, I would separate the time spent embedding the query from the time spent searching. In many systems the embedding call to an external API dominates, and the index is innocent. Client-side timing of each stage answers this in minutes.

If the search itself is slow or recall dropped, there are levers. Raising ef_search improves recall at a latency cost, and lowering it does the reverse, and it can be changed on a live collection. Heavy metadata filters can also hurt, particularly very selective ones, so I would see whether a particular filter is the common factor.

Then the structural question: at a few million records, am I still within single-node's intended envelope? The architecture documentation says fewer than around ten million records. If the projection says we will cross it, I would plan the move, to Chroma Cloud or another store, before it becomes an emergency. A larger instance is the short-term answer.

What separates strong from weak. A weak answer says "add an index" or "shard it", neither of which maps onto single-node Chroma. A strong answer connects RAM to the HNSW design, measures stages separately, names ef_search, and has a plan for the growth limit.

Scenario: a developer asks to expose Chroma to the browser

The question. "The front-end team wants the web app to call the Chroma server directly to save a hop. What do you say?"

A strong answer. No, and the reason is specific to the version. Self-hosted Chroma 1.x has no built-in authentication or authorisation. The 1.0 rewrite removed the old provider system, and the environment variables that tutorials still show for it protect nothing. Anyone who can reach the port can read every collection and delete them. A browser holding direct access would mean every user, and anyone who opens the developer tools, has that power.

The design I would offer instead is a thin retrieval API that authenticates callers, restricts which metadata fields can be filtered, returns only what the page needs, and is the only client of Chroma. Chroma itself sits on a private network. If a proxy is preferred, it must terminate TLS and enforce authentication, and the client passes the credential through HttpClient(headers=...).

I would also mention smaller hardening points: allow_reset stays false, CORS origins are explicit and not a wildcard, and the Docker default binds 0.0.0.0, so the port should be published only on a private interface.

What separates strong from weak. Weak answers propose the old auth environment variables. Strong answers know they are gone, identify the trust boundary, and offer an alternative that still achieves what the developer wanted, a simple architecture.

Scenario: moving to a better embedding model

The question. "We found a better embedding model. How do we switch without downtime?"

A strong answer. You cannot change the model of an existing collection in place. The first record fixed the dimension, and even with matching dimensions the old and new vectors live in different spaces. So it is a migration, and the pattern is blue-green.

Create a new collection with a versioned name, for example docs-v2, set its space and HNSW parameters deliberately because those cannot change later, and re-ingest from the source documents, not by copying vectors. Run the evaluation set against both collections and compare hit rate. Because the collection name is read from configuration, the cutover is a configuration deploy. Keep the old collection for a rollback window, then delete it.

Re-embedding through an API costs money and time, so estimate both first, and keep writing to the old collection until cutover or replay changes afterwards.

What separates strong from weak. Weak answers try modify or "re-embed in place". Strong answers explain why in-place is impossible, use a versioned name, measure before cutover, and handle writes during the migration.

Trade-off: one collection per customer or a tenant metadata filter

The question. "We are building a multi-customer product. Do we put each customer in their own collection or one big collection with a tenant_id field?"

A strong answer. It depends on the isolation need and the deployment, so I would ask both.

One collection per customer gives the cleanest separation. A forgotten filter cannot leak data, deleting a customer is a single delete_collection, and in distributed Chroma and Chroma Cloud it is the recommended pattern, because collections have isolated cold starts and rate limits and Cloud supports up to a million of them. On single-node it costs little, as long as the data fits in memory.

One shared collection is simpler to operate and cheaper in object count, but every query must carry the tenant_id filter. One missed filter leaks data between customers, so I would centralise query construction so the filter cannot be omitted, and test it. Highly selective filters can also behave badly in HNSW search.

I would add that on self-hosted Chroma, the tenant and database hierarchy is a namespace, not a security boundary, because there is no built-in auth. Real isolation needs a proxy or application layer that maps an authenticated identity to a fixed tenant and database.

My default for a product with contractual isolation or privacy deletion requirements would be a collection per customer, behind my own API.

What separates strong from weak. Weak answers say "tenants give isolation". Strong answers separate namespacing from security, and tie the choice to deletion, leak risk and the deployment mode.

Trade-off: Chroma, pgvector, Qdrant or FAISS

The question. "When would you choose Chroma, and when something else?"

A strong answer. I choose on operational fit, not on a feature list.

Chroma is attractive when the team wants a retrieval database with a very small learning curve, embedded in a notebook or run as a single server, with metadata and full-text filtering and an embedding-function abstraction built in. It is strong for prototypes, internal tools and moderately sized production systems on a single node.

pgvector fits when the data already lives in PostgreSQL and you want vectors in the same transactions and backups as the rest of your records, with a team that already operates Postgres. Qdrant fits when you want a dedicated vector service with its own filtering features and a clustering story you control. FAISS fits when you want a library, not a service, and are happy to manage persistence, metadata and filtering around it.

Chroma-specific considerations I would state honestly: self-hosted 1.x has no built-in auth, so I must supply it; single-node is for fewer than about ten million records and the index sits in RAM; and some features, such as the Search API with hybrid ranking, forking and Schema-driven sparse indexes, are Cloud or distributed only. If hybrid retrieval is central and I want to self-host with no cloud dependency, that weighs against Chroma.

What separates strong from weak. Weak answers declare one tool the best. Strong answers tie each tool to a situation, and name Chroma's real limits without being asked.

Trade-off: self-hosted single node or Chroma Cloud

The question. "Should we run Chroma ourselves or use the managed Cloud?"

A strong answer. Self-hosting gives control and, if the data is small, low cost: one machine, one volume. The price is that backup, upgrades, monitoring and authentication are all ours. The backup story is a stopped-server or snapshot copy of the data directory, with restores that must be tested.

Chroma Cloud runs the same open-source distributed system, with tenant isolation, API-key auth, the full Search API, forking and Schema. It is billed on usage: writes, reads and storage, with each metadata or full-text predicate counting as extra query work. It also has quotas, for example a cap on results per query and on records per write, that I must design within.

For a team in the Gulf or Egypt the deciding question is often residency. Cloud's multi-tenant clusters are in AWS us-east-1 and GCP europe-west1, with single-tenant and bring-your-own-cloud options on request. If policy requires in-region data and no such option fits, self-hosting in a local cloud region is the answer.

My recommendation pattern: start self-hosted if the corpus is modest and the security team is comfortable with a proxy in front, and move to Cloud when scale, hybrid search or operational load justifies it, having kept ingestion idempotent so that migration is a re-ingest or a chroma copy.

What separates strong from weak. Strong answers consider residency, operational burden, feature availability and cost drivers, and keep the migration path open.

Depth probe: what happens when you call query

The question. "Walk me through what happens between collection.query(query_texts=[...]) and the results."

A strong answer. The client first needs a vector. With query_texts, Chroma uses the collection's embedding function to embed each string, using the persisted EF configuration, so the model runs in the client process in the Python case or wherever the EF points. With query_embeddings, that step is skipped.

The request goes to the server, where the gateway validates it, including the filter structure. Empty filters are rejected, and unknown operators fail. The query executor then searches the HNSW index for nearest neighbours under the collection's space, applies the where and where_document constraints, and consults the write-ahead log so that records written but not yet compacted into the index are visible. It returns up to n_results hits per query. If n_results exceeds the collection size you get everything with no error.

The response is column-major and nested per query input: ids[0] is the list for the first query. By default it includes documents, metadatas and distances, not embeddings. Embeddings, when requested, come back as NumPy arrays.

Distances depend on the space: squared L2 by default, one minus cosine similarity, or one minus the inner product. Smaller is closer.

What separates strong from weak. Strong answers mention the embedding step, the log consultation and the nested result shape. They show they understand why the recent write is visible immediately.

Depth probe: what is persisted and what is not

The question. "If I restart the server and reconnect from a fresh process, what do I get back and what must I supply again?"

A strong answer. Everything about the data persists: records, documents, metadata, the collection's configuration including the space and HNSW parameters, and, since 1.1, the embedding function's configuration, meaning the model name and settings. A fresh get_collection call rebuilds the EF from that. The index files and SQLite database live under the persist path, so they survive a restart if that path is a volume, and in Docker it is /data.

What I must supply again is anything secret or environmental. EF API keys are not stored, so the process needs OPENAI_API_KEY or whichever variable the EF was configured to read. Client-side settings and custom headers, such as a proxy credential, are per-client. A custom EF class must be importable and registered in the new process, which is why name, get_config and build_from_config exist.

One more trap is the volume path. Containers from before 1.0 mounted at /chroma/chroma. A compose file carried forward will start an empty server and look like data loss.

What separates strong from weak. Strong answers separate configuration from secrets, mention registration of custom EFs, and know the volume path change.

What a strong answer covers that a weak one misses

Across all these questions the same differences recur.

• A mechanism. Strong answers explain why: RAM and HNSW, the write-ahead log, persisted configuration, silent-ignore semantics. Weak answers list actions.
• An order of investigation. Strong answers start with the cheapest, most informative check. Weak answers try fixes in random order.
• Honesty about limits. Strong answers state that self-hosted 1.x has no auth, that single-node has a size envelope, and that several documented features are Cloud only or not released. Weak answers oversell.
• Measurement. Strong answers propose an evaluation set, client-side timings and logged distances. Weak answers rely on feel.
• A migration path. Strong answers treat model, dimension and space changes as blue-green migrations, never in-place edits.
• Version awareness. Strong answers pin versions and name the behaviour on a specific release.

For neighbouring topics, LangChain covers framework integration and RAGAS covers evaluating retrieval.

This is part two of three, the mid-level tips file. By now you have a Chroma-backed feature working, and the problems you meet are no longer "it will not install". They are quiet ones: results that are subtly worse, jobs that report success and change nothing, servers that are reachable by everyone. This file collects the errors that appear at this level, the practices that pay off most in order of leverage, practice cards to rehearse, and operational recipes you can paste into a runbook. Everything targets Chroma 1.5.9.

Errors you meet at this level

Each entry gives the symptom, the cause, and the fix. The messages are exact for 1.5.9.

The job succeeds and nothing changes

Symptom. An ingestion job reports success, but edited documents still show old text.

Cause. add on an ID that already exists is silently ignored, and update on an ID that does not exist is also ignored, with an error logged but nothing raised.

Fix. Use upsert with deterministic IDs, delete stale chunks by a doc_id filter first, and add a test that reads a record back after rewriting it.

Dimension errors after a model change

Symptom. InvalidArgumentError: Collection expecting embedding with dimension of 384, got 1536.

Cause. The first add fixed the collection's dimension, and the query side now uses a different model. Worse, if two models share a dimension no error appears and results are meaningless.

Fix. One collection per embedding model. Put the model in the collection name, and migrate by creating a new collection and re-ingesting from source.

The configuration you set did not apply

Symptom. You changed metadata or index settings through get_or_create_collection, and nothing changed.

Cause. When the collection exists, the extra arguments are ignored, and since 0.5.11 metadata is not overwritten either.

Fix. Use col.modify(...) for what can change, and a new collection for what cannot.

Trying to modify what cannot be modified

Symptom. unknown field 'space', expected one of 'ef_search', 'max_neighbors', 'num_threads', 'resize_factor', 'sync_threshold', 'batch_size'.

Cause. space and ef_construction are fixed at creation. The error message is the list of what you may change.

Fix. Decide the space before the first write. If it is wrong, create a new collection. Treat max_neighbors as creation-time as well, since the docs say so.

Empty filter rejected

Symptom. Expected where to have exactly one operator, got {} in get.

Cause. Dynamic filter code passed where={}.

Fix. Omit the argument when there are no conditions, and wrap multiple conditions in $and.

A metadata value Chroma refuses

Symptom. Expected metadata value to be a str, int, float, bool, SparseVector, list, or None, got {'a': 1} which is a dict, or TypeError: argument 'metadatas': Cannot convert Python object to MetadataValue, or Expected metadata list value for key 't' to be non-empty.

Cause. Nested dictionaries, None inside add, and empty arrays are not accepted.

Fix. One helper that every writer calls: flatten nested keys with dots, drop None, omit empty lists.

Oversized batch

Symptom. Batch size 5462 exceeds maximum batch size 5461.

Cause. One call carried more records than the server accepts.

Fix. Chunk by client.get_max_batch_size(), and in practice use 50 to 250 per batch with parallel writers for throughput.

Connection refused with a healthy server

Symptom. ValueError: Could not connect to a Chroma server. Are you sure it is running? while the server's own logs look fine.

Cause. chroma run binds localhost by default, or Docker did not publish the port, or the client points at the wrong host.

Fix. Check from the client's machine with curl http://HOST:8000/api/v2/heartbeat. Bind with --host 0.0.0.0 if remote access is intended, and publish the port on the right interface.

Wrong tenant or database

Symptom. Collection [x] does not exist, Tenant [x] not found or Database [x] not found. Are you sure it exists? although you know the collection exists.

Cause. The client is scoped to default_tenant and default_database, but the data lives elsewhere.

Fix. Pass tenant= and database= explicitly and print them at startup.

A 410 from the server

Symptom. HTTP 410 with The v1 API is deprecated. Please use /v2 apis.

Cause. An old client, or a script calling /api/v1 directly, against a 1.x server.

Fix. Upgrade the client. Use /api/v2/... endpoints in scripts and health checks.

Model download fails behind a proxy

Symptom. [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain on the first add or query using the default embedding function.

Cause. A TLS-inspecting proxy re-signs traffic with its own root CA, and Python does not trust it when downloading the ONNX model. If you see this on a company laptop, that is the usual reason.

Fix. Export the proxy's root certificate and point SSL_CERT_FILE or REQUESTS_CA_BUNDLE at it. Do not disable verification. Or copy the model into ~/.cache/chroma/onnx_models ahead of time.

Cloud-only calls on a local server

Symptom. NotImplementedError: Search is not implemented for Local Chroma, or Collection forking is not implemented for Local Chroma, or over HTTP Search operation is not implemented for local executor.

Cause. The Search API and forking are Cloud and distributed features.

Fix. Use query and get locally. Keep Cloud-only code behind an interface, so it is tested separately.

A documented command that does not exist

Symptom. error: unrecognized subcommand 'utils' when following the vacuum page.

Cause. The docs say chroma utils vacuum, but on 1.5.9 the command is chroma vacuum --path <dir>.

Fix. Use the form chroma --help shows. Stop the server first, since vacuum blocks reads and writes.

The reset that is refused

Symptom. Reset is disabled by config.

Cause. client.reset() needs allow_reset, which is off by default.

Fix. Leave it off in production. In tests, use fresh collection names, or an ephemeral client, instead of resetting.

Practices that pay off, in order of leverage

These are ordered by how much trouble each prevents for the effort it costs. If you only adopt the first five, you will avoid most production incidents.

1. Build ingestion on upsert with deterministic IDs. It makes every job safe to re-run and removes the silent-ignore class of bugs. Pair it with a delete-by-doc_id step when documents can shrink.
2. Set the distance space explicitly, at creation. Match your embedding model, normally cosine, because the default is l2 and you cannot change it later.
3. Keep the proxy or API in front of the server. Self-hosted 1.x has no built-in authentication, so reachability equals full access. The server lives on a private network, and your service is the trust boundary.
4. Pin versions. Server image and client on the same minor line, an exact tag such as chromadb/chroma:1.5.9, never latest, and remember that the GitHub release marked latest is a development build.
5. Version the collection name. Include the model and a revision, for example support-minilm-v2. Model changes then become blue-green swaps, and mismatches are visible in logs.
6. Build an evaluation set. Thirty to a hundred real questions with expected chunk IDs, scored as hit rate at k, run in CI. It is the only way to know whether a chunking, model or ef_search change helped.
7. Log distances. Best and worst distance per request, with the filter and timings. It reveals drift and empty answers before users do.
8. Back up and test the restore. A copy taken while the server is stopped, or an atomic snapshot, stored off the host. A backup that has never been restored is a hope.
9. Set migration_mode: validate in production. Schema changes then happen when you choose.
10. Sanitise metadata in one place. One function used by every writer: flatten, drop None, drop empty lists, convert IDs to strings.
11. Prefer a collection per customer when isolation matters, and remember tenants and databases are namespaces, not security.
12. Measure embedding time separately from search time. The embedding call is often the slow part.

Practice cards

Each card is a short drill. Do them on a scratch server, not on shared data. Answers are in the text under each card, so cover them as you work.

Card 1: the silent add

Create a collection with embedding_function=None and hand-made 2-number vectors. add id a with document "one". add id a again with document "two". Read it back.

The record still says "one", and no error was raised. Repeat with upsert and watch it change. Write down in one sentence why a nightly job should use upsert.

Card 2: space and distances

Build the same five documents into two collections, one l2 and one cosine. Query both with the same text and compare the ordering and the distance values. Then try col.modify(configuration={"hnsw": {"space": "l2"}}) on the cosine one.

You should see different numbers, similar ordering, and a clear error listing what can be modified. Note that the list does not include space.

Card 3: filter surprises

Add ten records, four without a status key. Run get(where={"status": {"$ne": "archived"}}) and count. Then run get(where={}). Then a $contains document filter with the wrong case.

The first returns records missing the key, the second raises an error, the third returns nothing. Write a filter builder that never produces an empty dict.

Card 4: the dimension trap

Create a collection with 3-number vectors, then add a 2-number one. Read the error. Now think: what would have happened if both models produced 3 numbers?

Nothing would have failed, and results would be wrong. Add the model name to your collection naming convention.

Card 5: batch limits

Call client.get_max_batch_size(). Try an upsert one record over that number with tiny vectors. Then time an upsert of 5,000 records in one call against batches of 200.

Record the numbers on your machine and keep them in the runbook.

Card 6: server hardening

Run Docker with the data volume at /data, a mounted config file with migration_mode: "validate" and allow_reset: false, and the port published on 127.0.0.1 only. Confirm you can reach it from the host and not from another machine. Call client.reset() and read the refusal.

Card 7: backup and restore drill

Stop the server, archive the data volume, start a second server on another port from the extracted archive, and run a known query. Time the whole thing.

The time you measure is a real number for your recovery plan.

Card 8: the Cloud boundary

On a local server, call col.search with an empty Search(). Check hasattr(col, "conditional"). Write down which features your design needs and mark each one local, Cloud only, or not yet released.

Card 9: evaluation set

Write ten questions with expected IDs against a real collection. Compute hit rate at 3 and at 5. Change ef_search through modify and recompute. Then change the chunking and recompute.

Card 10: client-side metrics

Wrap your query call so it logs embed time, search time, number of hits, best and worst distance, and whether a filter was used. Run twenty queries and read the log.

Quick triage order for a bad answer

When someone reports a wrong answer, resist the urge to change the prompt. Work in this order and stop at the first thing that explains it. First, log the retrieved chunks with their distances and read them. Second, confirm the query service and the ingest service use the same embedding model, by comparing the collection's recorded configuration with what each service builds. Third, confirm the space is the one the model expects. Fourth, print the exact filter that was sent. Fifth, open the collection with chroma browse and read ten records for truncated or boilerplate chunks. Only after those five checks is it reasonable to look at the model or the prompt, and by then you usually know which side the fault is on.

Operational recipes

These are working snippets for the situations you will actually face. Adjust names and paths.

Verify a server end to end

curl -s http://localhost:8000/api/v2/heartbeat
curl -s http://localhost:8000/api/v2/pre-flight-checks
curl -s http://localhost:8000/api/v2/version

The heartbeat returns a nanosecond timestamp, the pre-flight check reports max_batch_size and supports_base64_encoding, and the version call returns "1.0.0". That last value is the API version, not your package version.

Print what the client and collection believe

import chromadb

print("client package:", chromadb.__version__)
client = chromadb.HttpClient(host="localhost", port=8000)
print("heartbeat:", client.heartbeat())
print("max batch:", client.get_max_batch_size())

col = client.get_collection(name="support-articles")
print("count:", col.count())
print("config:", col.configuration_json)

Keep this as a script in the repository and run it after every deploy.

A safe metadata cleaner

def clean_metadata(meta: dict, prefix: str = "") -> dict:
    out = {}
    for key, value in meta.items():
        name = f"{prefix}{key}"
        if value is None:
            continue
        if isinstance(value, dict):
            out.update(clean_metadata(value, prefix=f"{name}."))
        elif isinstance(value, (list, tuple)):
            if len(value) == 0:
                continue
            out[name] = list(value)
        elif isinstance(value, (str, int, float, bool)):
            out[name] = value
        else:
            out[name] = str(value)
    return out

Arrays must be homogeneous, so add a check there if your sources mix types.

Idempotent re-ingest of one document

def reingest(col, doc_id, chunks, base_meta):
    col.delete(where={"doc_id": doc_id})
    col.upsert(
        ids=[f"{doc_id}:{i}" for i in range(len(chunks))],
        documents=chunks,
        metadatas=[clean_metadata({**base_meta, "doc_id": doc_id, "chunk": i})
                   for i in range(len(chunks))],
    )

Page through a collection safely

def iter_records(col, page=500):
    offset = 0
    while True:
        res = col.get(limit=page, offset=offset, include=["documents", "metadatas"])
        if not res["ids"]:
            return
        for i, doc, meta in zip(res["ids"], res["documents"], res["metadatas"]):
            yield i, doc, meta
        offset += page

Since 0.5.11, get orders by internal ID. Do not write to the collection while paging with offsets, because the pages can shift.

Delete a large slice in chunks

while True:
    result = col.delete(where={"source": "old-wiki"}, limit=10000)
    if result["deleted"] == 0:
        break

Stop-copy-start backup

docker compose stop chroma
tar -czf chroma-$(date +%F).tgz -C ./chroma-data .
docker compose start chroma

If you use a bind mount, archive that directory. If you use a named volume, snapshot it with your platform's tooling. Then restore the archive into a scratch server regularly.

Compose file with a validated config

services:
  chroma:
    image: chromadb/chroma:1.5.9
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - ./chroma-data:/data
      - ./config.yaml:/config.yaml:ro
    restart: unless-stopped

persist_path: "/data"
allow_reset: false
sqlitedb:
  migration_mode: "validate"

Send traces to a collector

export CHROMA_OPEN_TELEMETRY__ENDPOINT="http://otel-collector:4317"
export CHROMA_OPEN_TELEMETRY__SERVICE_NAME="chroma-prod"

Note the double underscore between the section and the key. Generate a first trace by calling the heartbeat, then look for it in your tracing backend. The server exports traces only, so metrics must come from the client.

Move data between a local server and Cloud

chroma login
chroma db create my-db
chroma copy --from-local --all --db my-db --host http://localhost:8000

Check the flags with chroma copy --help on your installed version before relying on this in a script, since the CLI is versioned separately from the Python package.

Blue-green a collection

1. Create support-v2 with its own space and HNSW settings.
2. Re-ingest from source with the new model.
3. Run the evaluation set against both and compare.
4. Change the collection name in configuration and deploy.
5. Watch the logged distances and the error rate.
6. After a rollback window, delete support-v1.

Pre-release checklist

• Server image and client pinned to the same minor line.
• Port reachable only from the retrieval service.
• allow_reset false and migration_mode set to validate.
• Space set explicitly. Collection name includes model and revision.
• Ingestion uses upsert, deterministic IDs and the metadata cleaner.
• Evaluation set passes at the recorded baseline.
• A restore has been tested this month.
• Traces reach the collector, and client logs record distances and timings.
• Nobody is relying on a Cloud-only or unreleased feature on a local server.

For the surrounding stack, the Docker guide covers the container side of these recipes, the LangChain guide the framework side, and Qdrant and pgvector are the alternatives to compare when requirements outgrow a single-node Chroma.

Where this picks up

By now you can build a retrieval pipeline on Chroma, filter it with where and where_document, tune an HNSW index, and run chroma run or a Docker container. This level is about a different question: what happens when other teams depend on the Chroma you operate, and you are the person paged when it misbehaves. The tool did not change, but the failure modes did. A beginner's bug costs one notebook. A platform owner's bug costs every team's retrieval quality at once, often without an error message.

Everything below is checked against Chroma 1.5.9 (Python package, released 2026-05-05). That is the latest stable release at the time of writing; the main branch publishes dev builds such as 1.5.10.devNNN that you should never deploy. When this guide says "on 1.5.9" it means the behaviour was run, not inferred from documentation. Where the documentation and the shipped package disagree, the guide says so, because a platform owner who copies a command from a docs page into a runbook without testing it will find out during an incident.

If any of the vector-store vocabulary is unfamiliar, the neighbouring guides on Qdrant, pgvector and FAISS cover the same problem space from other angles, and this guide refers to them where the comparison matters.

What you are actually operating

The most useful sentence in the official architecture documentation is that Chroma has the same five core components in every deployment mode. Knowing them lets you reason about a failure without knowing which mode you are in.

In local mode these components run inside your Python process. In single-node mode, the one you will most often run for a team, they run inside one server process. Metadata, documents and the write-ahead log live in a SQLite file, chroma.sqlite3, and each collection has HNSW index files in the same persist directory. In distributed mode the components are separate services; the log and indexes live in object storage, the catalogue in a SQL database, and SSD caches sit in front to reduce latency. Queries are routed to executors by rendezvous hashing on the collection ID, which has a consequence worth remembering: a collection is served from a particular place, and an idle collection is cold, so its first query pays a latency penalty. The official advice is to send warm-up queries.

The official OSS page contains a sentence that every platform owner should quote in a design document: most engineering effort goes to distributed Chroma and Chroma Cloud, and local Chroma "may temporarily lack some features". That is not a criticism. It is the product's own statement of where features land first, and you can verify it on 1.5.9. The Cloud Search API, collection forking and the Schema-driven sparse and hybrid search are not implemented locally. Calling col.search(...) in-process raises NotImplementedError: Search is not implemented for Local Chroma, and over HTTP against a single-node server it raises ChromaError: Error executing plan: Not implemented: Search operation is not implemented for local executor. fork() fails the same way. A team that prototypes against the Cloud feature set and then asks you to "run it on our own server" is asking for something that does not exist, and finding that out at design time is far cheaper than finding it out at launch.

Single-node failure modes

A single-node Chroma server is one process with one disk. That simplicity is the reason to choose it, and it determines every failure you can have. There is no replica to fail over to, so recovery means restoring state onto a new process, and the recovery time is bounded by how good your backups are.

Memory exhaustion. The HNSW index must fit in RAM. When it does not, the failure is not graceful degradation; it is the kernel's OOM killer ending the process, or a container runtime doing the same to a container with a memory limit. The server restarts, loads its indexes, and if the data set has grown past what the box can hold, it dies again. A restart loop with no application error is the signature. The cause is almost always growth nobody tracked, not a Chroma bug.

Disk and write failures. Because SQLite holds the write-ahead log and the documents, a full disk stops writes in ways that surface as server errors on add and upsert rather than as a clean quota message. Alert on disk usage of the persist volume well before it fills, and treat the persist directory as a unit: chroma.sqlite3 and the index directories belong together, and copying one without the other produces a store that does not agree with itself.

The blocking maintenance operation. chroma vacuum --path <dir> rewrites the SQLite store, and it blocks reads and writes while it runs. It is required once when upgrading a database created before 0.5.6, and the server logs a warning at startup when it is needed. You must stop the server first. If your platform serves production traffic from one node, this is planned downtime, and it belongs in a change window, not in an incident.

Silent client-side surprises. Several behaviours that look like failures are by design, and they generate support tickets. Adding an ID that already exists is silently ignored, not rejected, so an "ingest" job that re-runs after a partial failure can report success while changing nothing. Updating an ID that does not exist is also ignored, with an error logged but nothing raised. Duplicate IDs inside a single batch do raise DuplicateIDError. If your platform offers a thin ingestion wrapper, make it use upsert and have it verify counts afterwards, because the raw API will not tell a team that half their write was a no-op.

The v1 cliff. Since 1.0, the v1 REST API is gone. GET /api/v1/heartbeat returns HTTP 410 with {"error":"Unimplemented","message":"The v1 API is deprecated. Please use /v2 apis"}. A team still running a pre-1.0 client against your server will see that 410 on every call. The fix is a client upgrade, and your platform's compatibility matrix should say so before they discover it.

Conditional transactions are not here yet. The documentation describes collection.conditional() and txn.commit() for optimistic concurrency. On 1.5.9, hasattr(collection, "conditional") is False. Do not build a coordination design on it. If a team wants compare-and-swap semantics on records today, they need to solve it in their own application layer.

Sizing and scaling: memory breaks first

On single-node Chroma the component that breaks first is memory, and the official documentation gives you a rule of thumb you can plan against. For 1024-dimension vectors with three metadata fields and small documents, the number of embeddings in millions is roughly the RAM in gigabytes multiplied by 0.245: N = R x 0.245. Reserve at least a gigabyte for the operating system, and do not deploy on less than 2 GB at all. The published benchmarks give concrete anchors.

Latency in the same benchmarks was 8 ms mean and 29 ms at p99.9 on the t3.small, and 5 ms mean and 7 ms at p99.9 on the r7i.2xlarge. Treat these as shape, not guarantee: they assume the stated vector width and metadata, and your payloads are different. What you should do with the table is derive your own, by loading a representative sample, measuring resident memory per million records, and extrapolating with headroom. Disk should be at least RAM plus several gigabytes.

Two decisions follow from this. The first is a migration trigger written down in advance. The architecture documentation positions single-node for "typically fewer than 10 million records across a handful of collections". Choose a threshold below the physical limit, for example 60 percent of the memory budget, at which a ticket automatically opens to plan the move to Chroma Cloud or another store. A platform that waits until the OOM killer announces the limit has chosen the worst possible time for a migration.

The second is how to split data. On single-node, splitting into several collections neither helps nor hurts as long as everything fits in memory, so do not shard for performance. On distributed and Cloud deployments the advice reverses: shard per tenant or customer into separate collections, because collections have isolated cold starts and rate limits and Cloud supports up to a million of them. Write throughput is governed by batch size and concurrency. The documentation recommends batches of 50 to 250 records with concurrent writers, while the hard ceiling for a batch on a local server is client.get_max_batch_size(), which returns 5461 on 1.5.9. Exceeding it raises ValueError: Batch size 5462 exceeds maximum batch size 5461. A wrapper library should chunk by the server's reported maximum and then by your tuned batch size, whichever is smaller.

HNSW tuning is a platform concern because the parameters are partly immutable. On 1.5.9 the defaults are space='l2', ef_construction=100, ef_search=100, max_neighbors=16, resize_factor=1.2 and sync_threshold=1000. The space and ef_construction are fixed at creation. ef_search, num_threads, resize_factor, sync_threshold and batch_size can be changed later with col.modify(configuration={"hnsw": {...}}); the documentation treats max_neighbors as creation-time, so tell teams to do the same. Trying to modify the space fails with unknown field space, expected one of ef_search, max_neighbors, num_threads, resize_factor, sync_threshold, batch_size. Because the default distance is squared L2 and most text embedding models are trained for cosine similarity, a platform default of {"hnsw": {"space": "cosine"}} in your collection factory prevents a whole class of quality complaints whose cause is a choice nobody made.

The security model: Chroma does not authenticate

The most important fact in this section is the first one: self-hosted Chroma 1.x has no built-in authentication or authorisation. The official migration log for 1.0 states that Chroma no longer provides built-in authentication implementations. The old server settings such as CHROMA_SERVER_AUTHN_PROVIDER, CHROMA_SERVER_AUTHN_CREDENTIALS and CHROMA_SERVER_AUTHZ_PROVIDER appear in the reference only as legacy, and you should not teach them or configure them on a 1.x server. Anyone who can reach the port can read every collection, write to any of them, and call delete_collection. There is no per-collection permission to configure, because there is no identity to attach one to. You can see the empty identity yourself: /api/v2/auth/identity returns {"user_id":"","tenant":"default_tenant","databases":["default_database"]} regardless of who asks.

So the trust model is the network and whatever you put in front. The practical posture has four parts.

First, reachability. Run Chroma on a private network segment, restrict security groups and firewall rules to the services that need it, and never publish the port to the internet. Note the difference in defaults: chroma run binds localhost, while the Docker image and the config default bind 0.0.0.0. A container with -p 8000:8000 on a host with a public interface is exposed unless something else blocks it.

Second, a proxy that authenticates. Put a reverse proxy or API gateway in front that terminates TLS and enforces identity: OIDC, mutual TLS, or at minimum a token check. The Python client supports HttpClient(headers={...}) and the JavaScript client ChromaClient({headers}), so a service can present a bearer token or other credential that your proxy validates. Because the proxy sees every request, it is also where you add rate limiting, request logging and per-team routing.

Third, hardening the server itself. Keep allow_reset: false (the default), because client.reset() erases everything and fails by design with Reset is disabled by config unless enabled. Set cors_allow_origins to explicit origins rather than ["*"] if a browser app calls Chroma directly, and ask whether a browser should call it directly at all. Set sqlitedb.migration_mode: validate in production so the server refuses to auto-migrate its schema.

Fourth, keep secrets out of the data path. Embedding providers read their keys from environment variables such as OPENAI_API_KEY. The embedding function's configuration is persisted in the collection, but API keys are not, so every client needs the variable in its own environment. That is the right behaviour, and it means your secret manager must deliver provider keys to each client team, not to the server. Use api_key_env_var="MY_VAR" when a team's variable name is non-standard. A secret store such as Vault fits here; the principle is that the Chroma server never needs to hold a provider credential.

The supply chain. Pin the image by exact tag, and preferably by digest, for example chromadb/chroma:1.5.9. Images are published on Docker Hub and on ghcr.io/chroma-core/chroma. Mirror the image into your own registry so a deploy does not depend on a public registry being reachable, and scan it as you would any other image. The Python package also installs the chroma CLI, and the default embedding function downloads an ONNX model at first use from an S3 URL into ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2. That download is a runtime fetch from outside your network. In a locked-down environment, pre-populate that directory in your image build so a pod does not reach out on first request, and so a proxy that inspects TLS does not break it. The failure is [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain, and the fix is trusting the proxy CA through SSL_CERT_FILE or REQUESTS_CA_BUNDLE, never disabling verification. The container side of this, including digests, SBOMs and signing, is covered in the senior Docker guide.

Multi-tenancy: model, isolation and the per-customer pattern

Chroma's data model is tenant, then database, then collection. The official definition says access control, quota enforcement and billing are scoped at the tenant level. That statement is accurate for Chroma Cloud. For a server you run, only the namespacing half holds, as the previous section showed. The distinction decides your design.

For self-hosted Chroma you have three isolation strategies, in increasing strength. The weakest is metadata filtering: every record carries a tenant_id and every query includes where={"tenant_id": ...}. It is cheap, but one forgotten filter in one team's code leaks another's data, and it provides none of the operational isolation: a heavy tenant slows everyone. The middle option is a collection or database per tenant on a shared server, scoped through the AdminClient, which provides create_tenant, create_database, get_database, delete_database and list_databases. Combined with a proxy that maps identities to allowed tenants, this gives a real access boundary, though the tenants still share memory and CPU. The strongest is a server per sensitive tenant, which costs more and isolates both data and noisy neighbours. Choose by the consequence of a leak, not by convenience.

On Cloud and distributed deployments the recommended pattern is one collection per customer. The documentation says it is cheaper and faster than one big collection with a filter, and it isolates cold starts and rate limits so one customer's burst does not degrade another's. Collections are limited to one million per deployment, and many customers each with a modest collection is the shape the system is built for. The quota table matters for planning: records per collection are capped at 5,000,000, a collection holds up to 4,096 embedding dimensions, and concurrent reads and writes per collection are each 10. A customer who needs more than ten parallel readers needs a design conversation, not a quota bump.

The metadata size limits on Cloud also shape a tenant model. A record can carry at most 32 metadata keys, keys are limited to 36 bytes, a metadata value to 8,182 bytes, a document to 16,384 bytes, and a where clause to 8 predicates. Design your standard metadata schema within those numbers even if you self-host, because a team that ships a 40-key schema on your server cannot later move to Cloud without rewriting its data model. Metadata values may be strings, integers, floats, booleans or non-empty homogeneous arrays of those; nested dictionaries are rejected, and None values fail on add with Cannot convert Python object to MetadataValue. A platform-provided helper that flattens nested structures and drops None keys saves every team the same debugging session.

The embedding model is a versioned dependency

Every record in a collection was embedded by a particular model, and every query must be embedded by the same one. The dimension is fixed by the first add, and a mismatch raises InvalidArgumentError: Collection expecting embedding with dimension of 3, got 2. That error is the friendly case. The dangerous case is two different models that happen to share a dimension: nothing errors, queries return results, and relevance is quietly wrong. As the platform owner you are the only person positioned to prevent this, because individual teams see only their own collection.

Since 1.1, the embedding function configuration is persisted server-side with the collection, so get_collection(name="docs") resolves the function without the caller passing it. Clients and servers older than 1.1, and JavaScript clients older than 3.0.4, still need the function passed explicitly. Two consequences follow. A custom embedding function must implement the current protocol, with name(), get_config() and build_from_config() and the @register_embedding_function decorator, or it cannot be rebuilt by another client. And the persisted configuration records which model, not the key, so deploys need the right environment variable in every consuming service.

Changing the model is a migration, not a setting. Neither the embedding model, the dimension nor the distance space can be changed in place. The pattern is blue/green: create a new collection with the new model, re-ingest from your source of truth, validate retrieval quality against a fixed evaluation set, switch the application's collection name through configuration, and keep the old collection for a rollback window before deleting it. This is why your platform should store the original documents somewhere other than Chroma. Chroma can hold the text, but a re-embed pipeline that reads from the document store of record is the thing that makes a model upgrade a routine job rather than a reconstruction effort. On Cloud, fork() makes the copy step near-instant and copy-on-write, which is useful for evaluating a change on a branch of an index; locally it raises NotImplementedError: Collection forking is not implemented for Local Chroma.

Evaluation is the part teams skip. A re-embed is only safe if you can say whether retrieval got better or worse, and that needs a fixed set of queries with known good answers, run before and after. Tools for this live in the neighbouring guides: RAGAS for retrieval and answer metrics, and Langfuse for tracing which chunks reached the model in production. A platform that offers the blue/green workflow without the evaluation gate will produce confident, wrong migrations.

For the default model, all-MiniLM-L6-v2 at 384 dimensions, remember what it is: a convenient default for prototypes. A platform default should be an explicit, documented choice, and the collection metadata should say which one. In Python the default runs through ONNX, and in JavaScript it needs the @chroma-core/default-embed package.

Upgrades, backups and recovery

Upgrades are where a platform owner's discipline shows. The rules are few and strict. Pin exact versions of the server image and the client library, and keep both on the same minor line; the 1.x line moved quickly (1.1 persisted embedding configuration, 1.5.3 added Python 3.14 support and removed the pydantic v1 layer, 1.5.7 added get_collection_by_id), and a client newer than its server may call methods the server lacks. Read the release notes at the GitHub releases page before each bump, and remember that the release labelled "latest" there can be a dev build from main, so select the stable tag, not the top of the page.

Set sqlitedb.migration_mode: validate in production. The default, apply, lets a new server version migrate your SQLite schema on startup, which is convenient and also irreversible. With validate, the server refuses to start against a schema it would need to change, so a surprise image bump becomes a refused start rather than a silently migrated database you cannot roll back. Do the migration deliberately: snapshot the volume, switch to apply for the upgrade window, confirm health, switch back.

The version history holds traps that still catch teams who inherit old data. Moving to 1.0 changed the Docker data path from /chroma/chroma to /data, so a compose file that still mounts the old path starts a server that looks healthy and empty. Opening pre-0.4 duckdb or parquet data produces a message telling you to pip install chroma-migrate and run chroma-migrate. Databases from before 0.5.6 need the one-time chroma vacuum. And the 0.5.11 changes, where get() returns results ordered by internal ID and get_or_create_collection no longer overwrites existing metadata, matter if a team has code written against older behaviour.

Backups have no built-in command on single-node. The official options amount to two: stop the server and copy the persist directory, or snapshot the volume at the storage layer. Either way you copy the entire persist_path, meaning chroma.sqlite3 and the index directories together. A snapshot of a running server may catch the files at inconsistent moments, so prefer a quiesced snapshot or a stopped copy, and test restoration on a schedule, because an untested backup is a hope. A second route is logical: chroma copy moves collections between local and Cloud, for example chroma copy --from-local --all --db my-db, which is also how you migrate off a node that is outgrowing its memory.

Define the recovery objectives out loud. Because the vectors can be regenerated from source documents, your real recovery path for many collections is a re-ingest, not a restore. The question is how long a full re-embed takes and what it costs in provider API calls. If that number is days, backups are your primary protection; if it is an hour, a rebuild may be cheaper to maintain than backup tooling. Know which of those two worlds you are in per collection, and write it next to the collection's owner.

Observability: traces, health and the signals you must build

The Chroma server exports OpenTelemetry traces only. There is no documented built-in metrics endpoint for single-node, and that single fact shapes your monitoring design: you will not scrape a /metrics page the way you do with many other services. Configure tracing with the open_telemetry block in the YAML config or the environment variables CHROMA_OPEN_TELEMETRY__ENDPOINT, CHROMA_OPEN_TELEMETRY__SERVICE_NAME (default chromadb) and OTEL_EXPORTER_OTLP_HEADERS. Note the double underscore for nested keys. The per-crate filters let you turn up detail for one component, such as chroma_frontend, without drowning the collector. The official compose example wires Chroma to the OpenTelemetry Collector, which receives OTLP on 4317 (gRPC) and 4318 (HTTP), and to Zipkin on 9411. See the OpenTelemetry guide for the collector side.

port: 8000
listen_address: "0.0.0.0"
persist_path: "/data"
allow_reset: false
sqlitedb:
  hash_type: "md5"
  migration_mode: "validate"
open_telemetry:
  service_name: "chroma"
  endpoint: "http://otel-collector:4317"
  filters:
    - crate_name: "chroma_frontend"
      filter_level: "trace"

Mount that at /config.yaml in the container. Because the server gives you traces and little else, you build the rest from outside. Four signals cover most of what a platform owner needs.

Liveness and readiness. /api/v2/heartbeat returns a nanosecond timestamp and /api/v2/pre-flight-checks returns the maximum batch size. Probe both from your orchestrator, and remember that a heartbeat proves the process answers, not that a query returns good results. Add a synthetic query: a canary collection with a handful of known documents, queried every minute, asserting that the expected ID is the top result. That check catches index corruption, a wrong embedding model and a stale deployment in one assertion.

Host metrics. Because memory is the scaling limit, resident memory of the server and free space on the persist volume are your two most important graphs. Export them with your normal node or container metrics, graph them in Prometheus and Grafana, and alert on the trend, not only the threshold. A line climbing 2 percent a week gives you months; a step change after a bulk load gives you hours.

Client-side latency and error rates. Wrap the client in your platform library and emit a histogram per operation and per collection, with the error class as a label. This is where ingest-batch failures show up, because the server does not report them as metrics. Tracing integrations such as OpenLLMetry, OpenLIT, Braintrust and DeepEval exist on the client side as well.

Retrieval quality. This is the signal that has no infrastructure equivalent. A healthy server can return irrelevant chunks. Sample production queries and the chunks returned, and review them on a cadence, with an evaluation set run on a schedule.

Cost: RAM on your side, bytes on the Cloud side

Self-hosted cost is dominated by memory, because the index must sit in RAM, so the cost of a collection is roughly the instance size needed to hold it plus a replica or a snapshot for safety, plus engineer time. The formula above converts record counts to instance sizes, and a platform can publish a simple chargeback: cost per million records at your chosen dimension. The trap is dimension. A model that produces 3072-dimension vectors uses roughly three times the memory per record of a 1024-dimension one, so the embedding model choice is a cost decision made far from the finance team. Surface it at design review.

Chroma Cloud prices by usage, using the official pricing page. Writes cost $2.50 per logical gibibyte written, whether the operation is an add, update or upsert, and compaction is not billed. Reads cost $0.0075 per tebibyte queried plus $0.09 per gibibyte returned, and each metadata or full-text predicate counts as an additional query, with a regular-expression or full-text string of N characters billed as N minus 2 queries. Storage is $0.33 per gibibyte-month, prorated hourly, and the SSD caches are not billed. Forking costs $0.03 per fork plus incremental storage. New accounts receive $5 in credits, and billing aggregates per account.

Two consequences stand out. The read price has a returned-bytes component, so a query that returns documents and embeddings for 300 results costs far more than one that returns only IDs and metadata. Teaching teams to set include narrowly is a real cost lever as well as a latency one. And the write price is per logical gibibyte, so a pipeline that re-ingests the whole corpus nightly "to be safe" pays for the whole corpus nightly. Use upsert for changed documents and a content hash to detect them.

Chroma Cloud versus self-hosting

Chroma Cloud runs the same open-source distributed system as the managed service. Multi-tenant clusters run in AWS us-east-1 and GCP europe-west1, and single-tenant and bring-your-own-cloud deployments are available on request. Data stays in the region you choose, and the posture includes SOC 2 Type II and customer-managed encryption keys through the Schema. For teams in the Gulf or Egypt, neither multi-tenant region is local, so the residency conversation needs an answer before the evaluation, not after. Some Cloud CLI features, chroma db and chroma browse among them, are available in the AWS region only, which is worth knowing when you pick one.

Cloud authentication uses API keys that begin with ck-, sent as the x-chroma-token header, and a key can be scoped to one database. The CLI stores profiles in ~/.chroma/credentials and the active one in ~/.chroma/config.json. For CI use chroma login --profile ci --api-key ck-.... The command chroma db connect <name> --env-file writes CHROMA_API_KEY, CHROMA_TENANT and CHROMA_DATABASE into a .env file, and the file must never be committed. In a platform setting, issue one scoped key per consuming team, store it in your secret manager, and rotate it on a schedule.

The Cloud-only capabilities are the reason to choose it. The Search API (generally available since 1.5.1/1.5.2) offers a builder with Search, K, Knn and Rrf, supports hybrid search with reciprocal rank fusion, and returns scored rows. One trap deserves a sentence of its own: RRF requires return_rank=True on every Knn in the fusion; without it the fusion runs on distances and produces wrong results with no error. The read_level argument trades consistency for latency: INDEX_AND_WAL is the default, INDEX_ONLY may miss writes that are not yet compacted, and INDEX_AND_BOUNDED_WAL sits between. Schema controls which indexes exist per key; sparse vector indexes must be declared at collection creation and cannot be removed, and filtering on a disabled index raises an error, so decide at creation. For Cloud, query() and get() continue to be supported and migration to Search is optional.

from chromadb import Search, K, Knn, Rrf

hybrid = Rrf(
    ranks=[
        Knn(query="refund policy", return_rank=True),
        Knn(query="refund policy", key="sparse_embedding", return_rank=True),
    ],
    weights=[3.0, 1.0],
)
s = (Search()
     .where(K("category") == "billing")
     .rank(hybrid)
     .limit(10)
     .select(K.DOCUMENT, K.SCORE, "title"))
res = col.search(s)   # Cloud only; raises on local and single-node servers

The hybrid search above depends on a sparse index declared in the collection's Schema at creation, so it will not work on an existing collection that lacks one.

Governance and incident playbooks

Governance for a vector store is mostly three questions answered in writing: who owns each collection, what data is allowed in it, and when does it expire. A collection with no owner is the one that fills the disk. Keep a registry, which can be a collection in the same server or a table elsewhere, listing each collection's team, embedding model, source of truth, retention and sensitivity. Embeddings are derived from your text, so if documents or metadata hold personal data, treat the whole collection as holding it, and make sure deletion requests reach it. col.delete(where={...}) supports predicate deletes, and for large ones the documentation recommends limit, for example col.delete(where={"user_id": "123"}, limit=10000), which returns {'deleted': n} and can be looped.

Four incident playbooks cover most of what will page you.

The server will not stay up. Check for an OOM kill first: container exit code 137 or the kernel log. If memory is the cause, do not just raise the limit and restart. Find which collection grew, decide whether it can be shrunk, split or moved, and only then resize. Order of action: restore service by moving to a larger instance, then fix growth.

Retrieval quality collapsed. Nothing errors, but answers are wrong. Check, in order: did a deployment change the embedding model or its version for ingestion or for queries; did the distance space differ from what the model expects; did a re-ingest change chunking; did a team start writing with a different dimension model into the same name. The collection metadata lineage from earlier is the fastest tool here.

Data was deleted. On a server with no authentication, deletion is a network event. Stop traffic at the proxy, identify the caller from proxy logs, and restore from the last verified backup. This is why the proxy's request logging is not optional, and why a nightly backup you have tested is worth more than any permission design.

The upgrade went wrong. If you ran with migration_mode: validate, the server refused to start and your data is untouched; roll the image tag back. If you applied the migration, restore the snapshot you took beforehand. Never improvise on the only copy.

Where Chroma stops

A platform owner's honesty about limits is a service to the teams. Chroma is strongest when you want a simple, developer-friendly retrieval database that is easy to embed, easy to start and cheap to run at modest scale. It stops being the right answer in recognisable situations.

When you need built-in authentication and per-tenant authorisation on a server you run, Chroma 1.x does not provide it, and you are building it in a proxy. A database with native roles, such as a relational store, may fit better; pgvector keeps vectors inside PostgreSQL and inherits its roles, row-level security, backups and replication, which for many organisations is the decisive advantage. When your data is already in Postgres and the scale is moderate, that is often the simplest platform decision.

When you need very large single indexes with rich filtering, quantisation options and production features such as replication and sharding on infrastructure you operate, a dedicated engine such as Qdrant is built around those concerns, with a server designed for self-hosted clustering. Chroma's own answer to scale is its distributed system and Cloud, so the question becomes whether you want to buy that or operate a different engine.

When you need a library, not a database, meaning an index inside a batch job with no server, no metadata store and maximum control over the algorithm, FAISS is the usual choice. It makes you build everything around the index, which is the point.

When you need strong transactional semantics across records and other data, the in-flight conditional-transaction work is not in 1.5.9, and a relational database is the safer foundation today.

When you need hybrid keyword and vector search on a server you operate, remember that the Search API and Schema-driven sparse search are Cloud features. Local Chroma supports where_document with $contains and $regex, which is substring and pattern matching, not ranked keyword relevance. If ranked hybrid retrieval is a hard requirement and Cloud is not an option, evaluate alternatives honestly.

None of this is an argument against Chroma. It is an argument for writing the decision down: the criteria that made Chroma the choice, and the signals that would make you reconsider. A platform decision with documented exit criteria ages well; one without them becomes a legacy system nobody dares touch.

Running Chroma as a platform for other teams

Everything above becomes a service when you offer it to others. The goal of a platform is that a team can get a working, safe, observable retrieval store without becoming Chroma experts, and without you becoming the bottleneck. Four ideas carry most of the weight.

A paved path. Provide one blessed way to get a collection: a Terraform module or Helm chart for the server (see Terraform, Helm and Kubernetes for the surrounding tooling), a client wrapper library, and a template repository with ingestion and evaluation scaffolding. The wrapper sets the distance space, records lineage metadata, flattens metadata, chunks batches within server and Cloud limits, uses upsert, propagates the tenant and database, and emits metrics. A team that follows the paved path inherits your decisions. A team that goes off it owns its own risks, and that trade should be explicit.

A contract. Publish what the platform promises: supported versions, a deprecation policy, expected latency for collections under a size, backup frequency, restore time, and what is explicitly not offered, with authentication and cross-tenant isolation at the top of that list unless your proxy provides them. A support channel and an escalation path belong in the same document.

Self-service with guardrails. Teams create collections through your factory or pipeline, which enforces naming, ownership registration and size budgets. Use the quota idea even on self-hosted: a per-team ceiling on records, enforced by the registry and reviewed monthly, prevents one team from consuming the node's memory. For Cloud, use one scoped API key per team and per environment.

Operational reviews. Each quarter, review per-team size growth against capacity, the age of embedding models in use, retrieval-quality trend, restore-test results, and the version gap between your pinned release and the latest stable one. A gap of one quarter is normal; a gap of a year is a risk.

The agent ecosystem raises a new question for platform owners. The official chroma-mcp server, run with uvx chroma-mcp --client-type persistent|ephemeral|http|cloud, lets Claude and other agents read and write a Chroma instance. That is powerful and it inherits the no-authentication problem: an agent with an http client type pointed at your server can do anything the network allows. Decide which collections agents may touch, use scoped credentials, and prefer read-only paths in the proxy for agent traffic.

The review checklist

Use this as the standing checklist for design documents and pull requests that touch Chroma. Each line is a question a reviewer asks, not a rule an author memorises.

Deployment

• Is the image pinned to an exact tag, and mirrored in an internal registry?
• Does the persist volume have monitored free space, and a tested backup of the whole directory?
• Is allow_reset false, migration_mode set to validate, and cors_allow_origins explicit?
• Is the port reachable only from approved networks, with an authenticating proxy in front?

Data model

• Does collection metadata record embedding model, dimension, chunking version and owner?
• Was the distance space chosen deliberately, rather than left at the squared-L2 default?
• Do metadata values avoid nesting and None, and fit within the Cloud limits?
• Are IDs strings, stable, and written with upsert rather than add where re-runs are possible?

Operations

• Does a synthetic canary query run continuously against a known answer?
• Are memory and disk trends graphed, with a migration trigger below the physical limit?
• Is there a written re-embed procedure with an evaluation gate?
• Does the runbook use commands that were run on the deployed version, including chroma vacuum rather than the documented chroma utils vacuum?

Risk

• If the collection holds personal data, is there a deletion path and a retention rule?
• Does anything depend on features that exist only on Cloud, or only on main?
• What would make us leave Chroma, and who will notice?

The complete picture

Put together, the senior view of Chroma is a short chain of decisions. Pick the deployment mode from your scale, residency and feature needs, understanding that local and single-node lag Cloud in features. Size single-node by memory, with a migration trigger set early. Treat the network and a proxy as your security model, because the server has none of its own. Treat tenants as namespacing unless something you built enforces more. Treat the embedding model as a versioned dependency, migrated by blue/green with an evaluation gate. Pin versions, validate migrations, back up the whole persist directory and test the restore. Watch memory, disk and a canary query, because the server emits traces and not metrics. Count cost in memory on your side and bytes on the Cloud side. Write down the conditions under which you would switch to pgvector, Qdrant, FAISS or the managed service.

Where the series leaves you

You started by adding a few documents and querying them. You can now size a node, defend its security posture honestly, run a re-embed migration without losing quality, price the Cloud alternative, respond to the four incidents that actually happen, and say plainly when another system is the better answer. The next growth is outside this guide: evaluation of retrieval quality with RAGAS, production tracing of what your retrieval returns with Langfuse, and the container and cluster operations around the server in Docker and Kubernetes. Keep the fact record honest as versions move: re-run the commands in your runbook against each new stable release, because on this tool the docs and the package have not always agreed.

Sources

• Chroma documentation home
• Introduction
• Migration log
• Troubleshooting
• Open-source overview
• Architecture overview
• Distributed architecture
• Server environment variables
• Single-node performance and sizing
• Docker deployment
• Observability
• Vacuum CLI
• Copy CLI
• Collection configuration
• Delete data
• Embedding functions
• Cloud pricing
• Cloud quotas and limits
• Collection forking
• Search API overview
• Hybrid search
• Schema overview
• Chroma releases on GitHub
• Sample single-node config
• chromadb on PyPI

How senior interviews on Chroma differ

At the senior level nobody asks you what a collection is. The interviewer wants to know whether you can own a retrieval store that several teams depend on, and the questions arrive as design prompts, incident stories and arguments about money. A strong candidate does three things consistently. They state the constraint that decides the design before proposing anything. They name what breaks first and how they would notice. And they say what they would not build, because restraint is the clearest sign of someone who has run the system.

This file is organised the way those interviews run: system-design prompts, incident-response questions, trade-off arguments, then the leadership conversation. Every claim here is checked against Chroma 1.5.9, so you can repeat it without hedging. If you are asked about something you have not run, say so; the interviewer will trust the rest of your answers more.

The thirty-second senior answer

If you get a single sentence to describe your stance on Chroma, use something like this: "Chroma is a retrieval database with the same five components in every mode: gateway, log, query executor, compactor and system database. Single-node is simple and fast but bounded by RAM, and it has no built-in authentication in 1.x, so security is the network and a proxy. Search API, forking and sparse hybrid search are Cloud features. I treat the embedding model as a versioned dependency and migrate it blue/green with an evaluation gate."

Notice what that answer contains: the architecture, the scaling limit, the security fact, the feature boundary and the operating habit. Each is a hook the interviewer can pull on, and you have chosen the hooks.

System-design prompts

Design a retrieval store for ten product teams in one company

Begin with questions, because the answer depends on them. How many records per team and at what embedding width? Is any data personal or regulated, and where must it reside? Do teams need hybrid keyword and vector search? What is the tolerance for downtime?

A good answer then picks a mode with reasons. For a few million records in total, a modest data set, and a requirement to keep data in your own network, run single-node servers behind an authenticating proxy. If any team needs ranked hybrid search, forking for evaluation, or more than the single-node envelope, those needs point at Chroma Cloud or a different engine, because the Search API, forking and Schema-driven sparse search are not available on a server you run.

Then describe isolation honestly. A self-hosted 1.x server has no authentication, so tenants and databases are namespacing. You enforce the real boundary at the proxy by mapping an authenticated identity to an allowed tenant, or you run separate servers for teams whose data must never mix. Describe the paved path: a client wrapper that sets the distance space, records lineage metadata, flattens metadata, chunks batches, uses upsert and emits metrics. Describe the registry that records each collection's owner, model, source of truth and retention. Finish with the exit criteria: the memory threshold that triggers a migration plan, and the features that would reopen the decision.

What a weak answer misses: it names a mode but not the reason, treats tenants as security, and has no plan for the day the node is full.

Size a single-node deployment for twelve million records

This prompt tests whether you know the rule and distrust it. The official rule of thumb for 1024-dimension vectors with a few metadata fields and small documents is N = R x 0.245, where N is millions of embeddings and R is gigabytes of RAM. Twelve million records suggests roughly 49 GB of RAM before headroom, and the benchmark table puts a 64 GB instance at about 15 million, with the operating system's reserved gigabyte on top. A good answer says that out loud and then says what it does not cover: the rule assumes 1024 dimensions and small payloads, so you would load a representative sample, measure resident memory per million records, and extrapolate with margin.

Then reframe it. Twelve million is above the architecture documentation's guidance of fewer than about ten million records across a handful of collections for single-node. The senior answer is not "buy a bigger box". It is "this is near the boundary, so I would plan the move to the distributed system or Cloud now, and I would set an alert at sixty percent of the memory budget that opens a migration ticket". Mention that a restart loop with no application error is the signature of exhausting memory, and that the fix is to find the collection that grew, not to raise the limit and restart.

Design the re-embedding migration when the team switches models

The key fact is that the embedding model, the dimension and the distance space cannot be changed in place. Trying to modify the space fails with an unknown field space error listing the fields that can change. So the design is blue/green: a new collection with the new model, a re-ingest from the source of truth, an evaluation run on a fixed query set against both collections, a configuration switch of the collection name, a rollback window, and then deletion of the old one.

Add the points that distinguish senior answers. Two models with the same dimension will not raise an error when mixed, which is why you record the model and dimension in collection metadata and verify them in the wrapper. The re-embed reads from a document store of record, not from Chroma, because that is what makes the migration routine. The evaluation gate matters more than the copy: without a fixed set of queries with known good answers you cannot say whether quality improved. And budget the provider cost, because re-embedding a corpus is a bill. On Cloud, forking is near-instant and copy-on-write, which makes evaluating an index change cheap, but it is a Cloud feature and fails locally with Collection forking is not implemented for Local Chroma.

Design multi-region or residency-constrained retrieval for Gulf and Egyptian customers

State the constraint: Chroma Cloud's multi-tenant clusters run in AWS us-east-1 and GCP europe-west1, neither of which is in the Middle East. Single-tenant and bring-your-own-cloud deployments are available on request, which may satisfy a residency policy, and data stays in the chosen region. The alternative is self-hosting in a regional cloud, accepting the feature limits of single-node.

A strong answer does not claim the region question is solved; it frames it as a requirement to confirm with the vendor before committing, and it shows the fallback. It also notes that telemetry is not an issue on current versions: as of 1.5.4 Chroma no longer collects product telemetry. Then it handles the embedding provider, which is often the larger residency problem: if documents are sent to a hosted embedding API outside the region, the vector store's location does not matter. Running an embedding model locally, for example through an Ollama or Hugging Face embedding server function, keeps the text inside your boundary.

Design a hybrid search feature on a self-hosted Chroma server

The trap is that this cannot be done natively. Hybrid search with reciprocal rank fusion is part of the Search API, and on 1.5.9 col.search(...) raises NotImplementedError: Search is not implemented for Local Chroma in-process, and Search operation is not implemented for local executor over HTTP. A senior answer says so immediately, then offers the real options: use Cloud; run a separate keyword engine and fuse the ranked lists in your application with reciprocal rank fusion; or choose a different store for this feature. The local where_document filters, $contains and $regex, are case-sensitive substring and pattern filters, not ranked keyword relevance, so they should not be presented as hybrid search.

If the interviewer pushes on Cloud, mention the detail that reveals real use: every Knn inside Rrf needs return_rank=True, or the fusion operates on distances and returns wrong results without an error, and sparse indexes must be declared in the Schema at collection creation.

Incident-response questions

The Chroma server keeps restarting, and nothing is in the application logs

Say the first hypothesis immediately: memory exhaustion. The HNSW index must fit in RAM, and when the data grows past the box, the kernel or the container runtime kills the process, which restarts, reloads indexes and is killed again. Verify with the container exit code (137 indicates a kill signal, typically from the OOM killer) or the kernel log, and with resident memory graphs. Mitigate by moving to a larger instance to restore service. Then diagnose growth: which collection, which team, which ingestion job. Fix by splitting, shrinking, or migrating. Then prevent recurrence with a memory trend alert and a migration trigger set below the physical limit.

What separates senior from mid here is the order. Restore service, then root-cause, then prevent. A candidate who starts by reading Chroma source code during an outage has the order wrong.

Retrieval quality dropped after a Friday deploy; no errors anywhere

A healthy server can return irrelevant chunks, so you cannot rely on error rates. Walk the checklist in order of likelihood. Did the embedding model or version change for ingestion or for queries, so that stored vectors and query vectors come from different models? A same-dimension mismatch raises no error. Did a collection get recreated with the default distance space, which is squared L2, when the model expects cosine? Did chunking change? Did a new team write to an existing collection name? The collection metadata that records the model, dimension and chunking version is the fastest tool, and a canary query against a known answer would have caught it within a minute.

Mention what you would build afterwards: a synthetic canary, a sampled review of production queries and returned chunks, and an evaluation set run on a schedule. Tools like RAGAS and Langfuse are the usual companions for the measurement and tracing parts.

Someone deleted a production collection

On self-hosted 1.x this is a network event, because there is no authentication to refuse the call. Contain first: block the offending path at the proxy. Identify the caller from proxy request logs, which is why the proxy must log. Restore from the last verified backup, which means a copy of the whole persist directory, chroma.sqlite3 and index directories together, or a volume snapshot, restored to a new server of the same version and verified by counts and a golden query set. If the collection is rebuildable from source, compare the re-ingest time with the restore time and choose the faster.

The closing move is design, not blame: put authentication in front of the server, restrict who can reach the port, and add a game day that rehearses the restore. A candidate who answers "we would enable authentication on Chroma" has missed that built-in authentication was removed in 1.0.

A docs command fails in the runbook during an upgrade

The concrete case is the vacuum command. The documentation shows chroma utils vacuum --path <dir>, but on 1.5.9 it fails with error: unrecognized subcommand 'utils', and the working form is chroma vacuum --path <dir>. The senior point is the process: every command in a runbook is run on the deployed version in a staging environment before it is trusted, and docs-versus-package discrepancies are recorded. Add the operational detail: vacuum blocks reads and writes, so the server must be stopped first, and it is required once for databases created before 0.5.6.

After an upgrade, the server looks healthy but empty

Think about what changed at the boundaries. Moving to 1.0 changed the Docker data path from /chroma/chroma to /data, so a compose file still mounting the old path starts a fresh, empty store. Check the volume mount and the persist_path. Also check whether a pre-1.0 client is calling v1 endpoints, which return HTTP 410 with The v1 API is deprecated. Please use /v2 apis. Prevention is version pinning, a staging upgrade, and sqlitedb.migration_mode: validate so an unexpected schema change refuses to start rather than migrating silently.

Trade-off questions

Chroma single-node versus pgvector

Argue from the constraint. pgvector keeps vectors inside PostgreSQL, so you inherit roles, row-level security, backups, replication and the operational knowledge your team already has, and you can join vectors with relational data. That is a strong answer when your data is already in Postgres and your scale is moderate. Chroma is simpler to start, designed around retrieval with metadata and document filters, and offers a path to a managed distributed system. Chroma 1.x has no built-in authentication, which is a point in pgvector's favour for shared platforms. See the pgvector guide for the other side. The candidate who says "it depends" and then lists exactly what it depends on has answered well.

Chroma versus Qdrant versus FAISS

Frame them by what you want to own. FAISS is a library with no server and maximum control. Qdrant is a dedicated server engine you operate and cluster. Chroma sits between, with an easy embeddable database and a managed distributed option.

One collection per tenant or one shared collection with a filter

On Cloud and distributed deployments, one collection per customer is the documented recommendation: it isolates cold starts and rate limits, offboarding is a delete, and the collection name is a boundary a proxy can check. Collections can number up to a million. On single-node, splitting neither helps nor hurts performance if everything fits in memory, so decide on isolation and operational grounds. The shared collection with a tenant_id filter is cheapest but one forgotten where clause leaks data.

Cloud versus self-host

Walk through the dimensions: features (Search API, forking, Schema, sparse hybrid, SPANN and customer-managed keys are Cloud or distributed), operations (no node to size or restore), cost (usage pricing versus instances), and residency (US and EU regions, with single-tenant and BYOC on request). Give the cost mechanism, not a number: writes are billed per logical gibibyte, reads per tebibyte queried plus gibibytes returned, storage per gibibyte-month. Narrow include reduces returned bytes. The honest conclusion is that Cloud wins when the team needs its features or does not want to operate nodes, and self-hosting wins when residency, cost at modest scale or control dominates.

Arguing a trade-off to leadership

Leadership conversations are won with structure. Four moves recur.

State the decision and the cost of delay first. "We need to decide by Friday whether the retrieval store moves to a managed service, because the single node reaches its memory limit in about eight weeks at current growth." Leaders act on deadlines and consequences, not on architecture.

Offer two or three options with one recommendation. For example: stay on single-node and add a second node for recovery; move to Chroma Cloud; or move vectors into Postgres with pgvector. For each, give cost, risk, effort and what you give up. Then recommend one and say why.

Translate technical risk into business risk. "Chroma 1.x has no built-in authentication" becomes "anyone who can reach that port can read or delete all customer embeddings, so we must keep it on the private network behind a proxy, and that proxy is a project with an owner and a date." "Changing the embedding model is a migration" becomes "a model upgrade is a two-week project with an evaluation gate and a provider bill, not a configuration change".

Bring numbers you measured. Resident memory per million records from your own sample, the time a full re-embed took, the provider cost of that re-embed, the restore time from your last game day. A measured number from your system beats a vendor benchmark in any room.

What a strong answer covers that a weak one misses

• It names the constraint first: scale, residency, features or security.
• It states the security fact: self-hosted 1.x has no built-in authentication, and tenants are namespacing.
• It states the feature boundary: Search API, forking and sparse hybrid search are Cloud features.
• It treats the embedding model as a migration, with an evaluation gate.
• It orders incident response: restore, then root cause, then prevent.
• It uses measured numbers, and says what it has not verified.
• It has exit criteria for the technology choice.
• It distinguishes docs from reality: the vacuum command, the version string, conditional transactions not being in 1.5.9.

Sixty-second self-test

Answer without notes, then check against this file.

1. Name the five core components and say which one makes a write durable.
2. What does GET /api/v2/version return on a 1.5.9 server, and why?
3. Give the single-node sizing rule and its assumptions.
4. Which settings cannot be changed on an existing collection, and what do you do instead?
5. What are your three layers of defence on a server that has no authentication?
6. Which features exist only on Cloud or distributed Chroma?
7. What is the first thing you check when the server restarts in a loop?
8. What does add do with an ID that already exists, and what do you use instead?
9. What is the working command to vacuum a database on 1.5.9?
10. Which Cloud limit would break a pipeline that writes local-sized batches of 5,000 records?

If you hesitated on more than two, reread the matching section of the detailed guide.

How to use this file

The detailed guide explained how Chroma works as a platform. This file is the short list of things that bite when other teams are using it: traps that only appear at scale, habits that keep a shared service healthy, and checklists for reviewing pull requests and design documents. Each trap follows the same shape: the symptom you will see, the cause, and the fix. Everything is checked against Chroma 1.5.9.

Production traps that only appear at scale

The silent no-op write

Symptom. An ingestion job reports success, the collection count does not change, and documents that were edited upstream still return their old text.

Cause. Calling add with an ID that already exists is silently ignored. No error is raised. Likewise, update on a missing ID is ignored, with an error logged but nothing raised. A job that re-runs after a partial failure, or a pipeline that "adds" edited documents, looks healthy and changes nothing.

Fix. Use upsert for anything that can be re-run, and have your wrapper compare count() or fetch a sample of IDs after the write. Duplicate IDs inside a single batch do raise DuplicateIDError, so dedupe before you write.

The restart loop with no error

Symptom. The server restarts every few minutes. Application logs show nothing. Clients see connection errors.

Cause. The HNSW index no longer fits in memory and the OOM killer ends the process on each load. Growth went unnoticed because nobody graphed resident memory.

Fix. Check for exit code 137 or the kernel log. Restore service with a bigger instance, then find the collection that grew. Prevent it with a memory trend alert and a written migration trigger below the physical limit. The sizing rule is N = R x 0.245, with N in millions of 1024-dimension embeddings and R in gigabytes, plus at least a gigabyte for the operating system.

The wrong default distance

Symptom. Retrieval is mediocre and nobody can say why. The model documentation says it is trained for cosine similarity.

Cause. The default space is l2 (squared L2). It is fixed at creation and cannot be modified afterwards. Trying fails with unknown field space.

Fix. Set the space in your collection factory, configuration={"hnsw": {"space": "cosine"}}, and record the choice in collection metadata. For existing collections, create a new one and re-ingest.

The same-dimension model mix

Symptom. Results come back and look plausible but relevance is poor, only for some queries.

Cause. Two embedding models with the same dimension were used for ingestion and querying. Chroma raises a dimension error only when the sizes differ, as in Collection expecting embedding with dimension of 3, got 2.

Fix. Store model name and dimension in collection metadata, assert them in the wrapper, and add a canary query with a known answer.

The batch that works locally and fails on Cloud

Symptom. A pipeline written against a local server fails on Chroma Cloud.

Cause. The local maximum batch is reported by client.get_max_batch_size() and was 5461 on 1.5.9. Cloud limits writes to 300 records, results to 300 per query, and metadata to 32 keys per record, with a document limited to 16,384 bytes.

Fix. Write the wrapper to the stricter limits from the start, and batch within the 50 to 250 range the documentation recommends for throughput, using concurrency rather than large batches.

The Cloud-only feature in a self-hosted design

Symptom. A feature works in a Cloud prototype and fails when moved to your server.

Cause. The Search API, forking and Schema-driven sparse search are not implemented locally. You get NotImplementedError: Search is not implemented for Local Chroma in-process, or Search operation is not implemented for local executor over HTTP.

Fix. Make feature availability part of the design review. If the feature is required, the decision is Cloud, a different store, or application-side composition.

The unreleased feature in the docs

Symptom. Code copied from the Conditional Transactions page fails with an attribute error.

Cause. The page describes collection.conditional(), which is not in 1.5.9: hasattr(collection, "conditional") is False. It is main-branch work.

Fix. Do not design around it. If a team needs optimistic concurrency, build it in the application.

The documented command that is wrong

Symptom. chroma utils vacuum fails with error: unrecognized subcommand 'utils'.

Cause. The docs page runs ahead of the shipped CLI.

Fix. The working command on 1.5.9 is chroma vacuum --path <dir> [--force] [--timeout <secs>]. Stop the server first; vacuum blocks reads and writes.

The version string that looks wrong

Symptom. A monitor compares the HTTP version with the image tag and alerts.

Cause. /api/v2/version returns "1.0.0" on a 1.5.9 server. That is the API protocol version.

Fix. Verify deployment by image tag and by chromadb.__version__, not by the HTTP string.

The empty server after an upgrade

Symptom. After moving to 1.x, the server is healthy and has no data.

Cause. The container data path changed from /chroma/chroma to /data at 1.0, so the old volume mount is no longer where the server writes.

Fix. Mount the volume at /data, or set persist_path explicitly. Pin versions and test upgrades in staging against a copy of the data.

The 410 from an old client

Symptom. Every request returns HTTP 410 with The v1 API is deprecated. Please use /v2 apis.

Cause. A pre-1.0 client is calling a 1.x server. The v1 API is gone.

Fix. Upgrade the client. Publish a compatibility matrix so teams find out before they deploy.

The first query that fails behind a proxy

Symptom. The first add or query on a new pod fails with [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain.

Cause. The default embedding function downloads its ONNX model from an S3 URL on first use, and a TLS-inspecting proxy presents its own certificate authority.

Fix. Trust the proxy CA through SSL_CERT_FILE or REQUESTS_CA_BUNDLE, or pre-populate ~/.cache/chroma/onnx_models in the image. Do not disable certificate verification.

Platform-ownership habits

Pin everything. The server image, the client library and the embedding model each get an exact version. Keep client and server on the same minor line. When you read the GitHub releases page, remember the release labelled "latest" can be a dev build from main, such as 1.5.10.devNNN, so choose a stable tag.

Put a proxy in front, always. Self-hosted 1.x has no built-in authentication. Treat the proxy as the product: TLS, identity, rate limiting, request logging and per-team routing. Keep the port off public networks, and remember that chroma run binds localhost while Docker and the config default bind 0.0.0.0.

Write the config down. Keep a config.yaml in version control, mounted at /config.yaml, with allow_reset: false, sqlitedb.migration_mode: validate, explicit cors_allow_origins and the OpenTelemetry block. Remember the nested environment variables use a double underscore, for example CHROMA_OPEN_TELEMETRY__ENDPOINT.

Own the factory. Teams create collections through your wrapper, not by calling the API raw. The wrapper decides the distance space, writes lineage metadata, validates names (3 to 512 characters from a-z A-Z 0-9 . _ -, starting and ending alphanumeric), flattens metadata and drops None values, chunks batches, and uses upsert.

Keep a registry. One record per collection: owner, embedding model and dimension, chunking version, source of truth, sensitivity and retention. A collection with no owner is the one that fills the disk.

Keep the source of truth outside Chroma. The re-embed pipeline reads from the document store of record. That is what turns a model change from a crisis into a scheduled job.

Measure retrieval, not only uptime. Run a canary query every minute, sample production queries and results for review, and run an evaluation set after every change to the model, chunking or index settings. RAGAS and Langfuse are natural partners.

Narrow include. Returning only what the caller needs lowers latency everywhere and lowers the returned-bytes charge on Cloud, which is $0.09 per gibibyte returned. Embeddings are excluded by default; request them only when needed.

Rehearse the restore. Back up the whole persist directory, chroma.sqlite3 and the index directories together, from a stopped server or a quiesced snapshot. Then restore it onto a fresh server of the same version every quarter and compare counts and a golden query set.

Keep provider keys with the clients. The embedding function configuration is persisted in the collection but API keys are not. Deliver keys to the consuming services from your secret manager, such as Vault, and use api_key_env_var for non-standard variable names.

Set the exit criteria early. Write down the memory threshold that opens a migration ticket and the features that would reopen the choice of store. Keep the comparison to pgvector, Qdrant and FAISS current.

Checklist for a pull request that touches Chroma

Reviewers can paste this into the pull request template.

Writes

• Are IDs strings, stable across runs, and written with upsert where a re-run is possible?
• Are batches below the server's maximum and the Cloud 300-record limit?
• Are metadata values flat, with no nested dictionaries, no None, and no empty arrays?
• Are documents and metadata sized within the Cloud limits if migration is plausible?

Reads

• Is n_results set deliberately, with include narrowed to what is needed?
• Is the where filter non-empty? An empty where={} raises a ValueError.
• Are operators from the supported list, and is the full-text filter's case sensitivity understood?
• Does the code avoid search(), or is it explicitly Cloud-only?

Collections

• Is the distance space explicit?
• Is the embedding function the one recorded in collection metadata, with its key coming from the environment?
• Does anything call reset(), which is disabled by design in production?
• Does anything call delete_collection, and is that path reviewed and logged?

Operations

• Are versions of server, client and model pinned?
• Does the change add or alter a metric, a canary or a runbook entry?
• If it changes the model, dimension or space, is there a blue/green plan with an evaluation gate?

Checklist for a design document

Scope and scale

• How many records, at what dimension, growing how fast, and what is the memory budget?
• Where is the migration trigger, and who owns the response?
• Is the design within single-node limits, or does it need distributed Chroma, Cloud or another store?

Security and data

• Who can reach the port, and what authenticates them? If the answer is "nobody checks", the design is not finished.
• Are tenants used as a security boundary, and if so, what enforces it outside Chroma?
• Does the data include personal information, and how do deletion requests reach the collection?
• Where does the text go for embedding, and does that satisfy residency?

Quality

• What is the evaluation set, who owns it, and what is the threshold for rollback?
• What happens when the embedding model changes?
• Is hybrid search needed, and if so, how, given the Search API is a Cloud feature?

Operations

• What are the backup frequency, the restore procedure and the last verified restore?
• Which signals alert, and what do they page?
• What are the upgrade and rollback steps, with migration_mode stated?

Decision record

• Why Chroma, and what would reopen the decision?
• Which alternatives were considered, and what did each give up?

Arguments you will have, and how to settle them

"Can we just turn on authentication in Chroma?" Not on 1.x. Built-in authentication was removed in 1.0, and the old CHROMA_SERVER_AUTHN_* variables are legacy. The answer is a proxy, a private network, or Chroma Cloud with scoped API keys. Settle it by showing the empty response from the identity endpoint and agreeing who owns the proxy.

"Why not one big collection for everybody?" On a single node it performs the same as many collections if everything fits in memory, so the argument is really about isolation. A shared collection with a tenant_id filter leaks data the first time someone forgets the filter, and it ties every tenant's cold starts and rate limits together on distributed deployments. Settle it by deciding the consequence of a leak and picking the weakest isolation that survives it.

"We will re-embed later if we need to." Later is a project: a new collection, a re-ingest from source, an evaluation run, a configuration switch and a provider bill. Settle it by asking where the source documents live today. If the honest answer is "only in Chroma", the first task is to fix that.

"The server is healthy, so retrieval is fine." A heartbeat proves the process answers. It says nothing about whether the right chunk is returned. Settle it by adding the canary query and a scheduled evaluation, and by agreeing who looks at the result.

"The docs say it works." The docs and the package have disagreed on this tool: the vacuum command and conditional transactions are the two cases to cite. Settle it by running the command on the deployed version in staging, and recording the result in the runbook.

"Let us run it on the smallest instance." The documentation says not to deploy on less than 2 GB, and the sizing table shows a 2 GB machine holds about a quarter of a million records of the stated shape. Settle it with your own measured memory per million records, not with the table.

Practice cards

Card one. Create a collection with the default settings and inspect its configuration. Write down which values you would change in a factory and why.

Card two. Stop a test server, copy its persist directory to another machine, start a server of the same version on it and compare counts. Time the whole procedure.

Card three. Put a token-checking proxy in front of a test server, then try to reach it directly and through the proxy with and without a token.

Card four. Ingest two hundred documents with two different embedding models into two collections and compare ten queries by eye. Decide what an evaluation harness would need to automate the comparison.

Card five. Trigger each of these errors on purpose and record the exact message: a duplicate ID in one batch, an empty where, a name that is too short, a batch of 5,462 records. Add them to the team's error glossary.

Operational recipes

Check a server end to end.

curl http://localhost:8000/api/v2/heartbeat
curl http://localhost:8000/api/v2/pre-flight-checks
curl http://localhost:8000/api/v2/auth/identity

The heartbeat returns a nanosecond timestamp, the pre-flight check returns the maximum batch size (5461 on 1.5.9), and the identity call returns an empty user and the default tenant, which confirms that no authentication is happening.

Run a pinned, configured server.

docker run -v ./chroma-data:/data -v ./config.yaml:/config.yaml -p 8000:8000 chromadb/chroma:1.5.9

Vacuum after an old upgrade. Stop the server, then:

chroma vacuum --path ./chroma-data --force

Canary query.

import chromadb

client = chromadb.HttpClient(host="chroma.internal", port=8000)
col = client.get_collection(name="canary")
res = col.query(query_texts=["known canary phrase"], n_results=1)
assert res["ids"][0][0] == "canary-1", "retrieval canary failed"

The nested list in res["ids"][0][0] is because query returns results per query input.

Narrow delete with a limit.

result = col.delete(where={"user_id": "123"}, limit=10000)   # {"deleted": n}

Loop until the deleted count is zero when you are removing a large set, and log each pass.

Pre-cache the default model. In a locked-down image build, run one embedding call during the build with network access so ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2 is populated, or mount that directory from an internal artifact store.

Where to go next

With the traps and habits above in place, the highest-leverage next steps are outside Chroma itself. Build the evaluation set and the scheduled run that tells you when retrieval quality moves. Wire traces into your observability stack so you can see which chunks reached the model. And keep an eye on the supporting platform guides: Docker for the image and runtime side, Kubernetes for scheduling, and OpenTelemetry for the traces the server emits.