In Chroma, what happens to raw text passed to collection.add(documents=...)?

## What a collection actually is In Chroma, a *collection* is not just a table of vectors. It is a named bundle of four things that travel together: the vectors, the original document text, arbitrary JSON-ish metadata per record, and an **embedding function** — the callable that turns a string into a vector. That last part is what makes Chroma feel lightweight: because the collection knows how to embed, you can hand it raw text and never touch a model yourself. You get a collection with `get_or_create_collection(name=...)`, optionally passing `embedding_function=` and a `metadata=` dict for index settings. ## The shape of add() `collection.add()` takes several parallel arguments: - `ids` — a list of strings. **Required on every call.** Chroma does not generate ids for you; if you want UUIDs or content hashes, you produce them. - `documents` — the raw text, one string per id. Optional if you supply `embeddings`. - `embeddings` — precomputed vectors, one list of floats per id. Optional if you supply `documents`. - `metadatas` — one dict per id, whose values are scalars (string, int, float, bool). Optional. All supplied lists must be the same length and are matched **by position**, not by any key inside them. A single off-by-one in how you build these lists silently attaches the wrong metadata to the wrong text — a bug no exception will catch for you, so build the lists in one loop rather than three. ## Where the embedding happens The embedding call runs **in your process, client-side**, before anything is written. With the default function, that means an ONNX Runtime session in your Python process; with a hosted function such as `OpenAIEmbeddingFunction`, it means an HTTP call per batch out to the provider. Two consequences follow. First, a big `add()` is not a cheap write. Its latency is dominated by embedding, not by storage, and a hosted function makes it a network operation that can rate-limit or fail halfway. Batch your adds into chunks of a few hundred to a few thousand documents rather than one giant call, and be prepared to retry a chunk. Second, the very first call with the default embedding function downloads the model artifact to a local cache. In a container or a CI job with no outbound network, that is where an otherwise-correct script fails — and the error is about a model download, not about Chroma. ## Precomputed embeddings If you pass `embeddings=`, Chroma stores exactly those vectors and never calls the embedding function for that write. You may still pass `documents=` alongside them; the text is then stored purely as payload so results can carry it back. This is the path you take when a separate pipeline (a batch job, another service, a GPU box) already produced the vectors. The first write fixes the collection's dimensionality. Every later write must match it, or Chroma rejects the batch with a dimension-mismatch error. That check is on the *number* of dimensions only — it cannot tell you that two 384-dimensional vectors came from two different models, which is the far more dangerous mistake. ## add() is not upsert Re-running an ingestion script over the same corpus does not refresh it. Chroma treats an id that is already present as a duplicate: it warns and leaves the stored record alone, so an edited document keeps its stale vector. If your ingestion is meant to be re-runnable, use the upsert path or delete the ids first; if ids are meant to be new every time, derive them from something genuinely unique. A content hash makes a good id precisely because it makes re-ingestion idempotent — an unchanged document produces the same id and is skipped, while an edited one produces a new id. ## Metadata rules of thumb Metadata values must be scalars. Nested dicts and lists are not stored, so flatten (`"tags": "a,b"` or one boolean column per tag) before writing. Because metadata is what later filtering keys off, decide the field names during ingestion — retrofitting a field means rewriting the records that lack it. ## What to check after ingesting `collection.count()` tells you how many records landed, which immediately catches a partially-failed batch or a run that silently skipped duplicates. `collection.peek()` returns a small sample of records so you can eyeball that documents, metadata and ids line up the way you intended.