English for Chroma Embeddings

Chroma is often the first vector store developers reach for because it runs in-process with almost no setup, but that simplicity means the vocabulary around it is small and precise — getting a few terms wrong (like calling an embedding function a “model”) can make an otherwise clear explanation confusing.

Key Vocabulary

Collection — a named group of embeddings, documents, and metadata in Chroma, the basic unit you query against, similar to a table. “We keep FAQ answers and documentation pages in separate collections so we can weight search results differently for each source.”

Embedding function — the component responsible for converting raw text into a vector, either a built-in default or a custom one wrapping an external model’s API. “We swapped the default embedding function for one that calls our own fine-tuned model, since the built-in one didn’t capture our domain’s terminology well.”

Persistent client — a Chroma client configured to write data to disk rather than keeping it only in memory, so the collection survives a process restart. “We switched from the in-memory client to a persistent client once we needed the index to survive a redeploy.”

Metadata filter (where clause) — a condition applied alongside a similarity search to restrict results to documents matching specific attributes, such as source or date. “We’re not filtering by where={'source': 'docs'}, so the search is pulling in outdated blog posts alongside the current documentation.”

Distance function — the metric (typically cosine, L2, or inner product) Chroma uses to measure similarity between query and stored embeddings, configured per collection. “We changed the distance function to cosine because our embedding model was trained assuming normalized vectors, and L2 was giving inconsistent rankings.”

Common Phrases

• “Is this using the persistent client, or will the collection disappear when the process restarts?”
• “Are we filtering with a where clause, or does every query search the entire collection?”
• “What embedding function is this collection using — the default, or our custom one?”
• “Is the distance function set to cosine here, or is it still on the default?”
• “Should this be a new collection, or can we scope it with metadata inside the existing one?”

Example Sentences

Debugging a “no results” issue: “The collection was empty because we were writing to an in-memory client in one process and querying a persistent client in another — they were never the same store.”

Explaining a design choice in a PR: “We’re filtering on document_type in the where clause instead of creating separate collections per type, since the schema is identical and this keeps things simpler.”

Describing a migration: “We’re moving off Chroma’s default embedding function to our own hosted model so search quality stays consistent as we scale past local prototyping.”

Professional Tips

• Clarify whether a client is persistent or in-memory before debugging a “missing data” report — this single distinction resolves a large share of Chroma confusion.
• Name the embedding function explicitly when comparing search quality across environments — silently swapping it between prototype and production is a common, hard-to-trace bug.
• Use metadata filter rather than vague terms like “search restriction” — it maps directly to the actual where parameter and helps reviewers spot missing filters.
• Mention the distance function when search rankings look off — an unnoticed default can silently produce worse relevance than intended.

Practice Exercise

1. Explain the difference between an in-memory client and a persistent client.
2. Write a sentence describing what a metadata filter does in a Chroma query.
3. Describe why the choice of embedding function matters for search quality.