Chroma (ChromaDB) — Vector Database Documentation

Type: official-docs Tier: 1 (Official Documentation) Author(s): Chroma (chromadb) Date: docs accessed 2026-06-01 URL: https://docs.trychroma.com/ Accessed: 2026-06-01

Why This Source Matters

Project 02 computed cosine similarity over a tiny in-memory corpus by hand. That does not scale: ranking a query against millions of vectors by brute-force cosine is too slow. A vector database solves the storage + fast-retrieval problem. Chroma is the lab's vector DB for Project 03 (Semantic Search): it is open-source, pip install chromadb, runs embedded in-process (no server), and exposes exactly the collection → add → query loop the project is built around. It grounds every concrete claim about how a real vector store indexes and queries embeddings.

Key Claims

What Chroma is and its data model

• "Chroma is the open-source data infrastructure for AI." It is a vector database for storing and retrieving embeddings.
• Data is organized into collections. Each record in a collection has: an id, an embedding (the vector), an optional document (the original text), and optional metadata (key/value pairs used for filtering).
• You can bring your own embeddings or attach an embedding function ("use any embedding model. OpenAI, Cohere, Hugging Face, sentence-transformers, and more"). With an embedding function attached, Chroma embeds text for you on add and query.

Indexing — HNSW / approximate nearest neighbor

• Chroma "uses an HNSW (Hierarchical Navigable Small World) index to perform approximate nearest neighbor (ANN) search" in single-node deployments. (This is approximate — it trades a small amount of recall for large speedups; see sources/papers/hnsw.md.)
• The distance function is set by the collection's space parameter, with three options:
• l2 — squared L2 (Euclidean) distance. This is the default.
• cosine — cosine distance; for "text embeddings or cases where you care about direction rather than scale."
• ip — inner product.
• Key tunable HNSW parameters: ef_construction (candidate list size at build time, default 100), ef_search (candidate list size at query time, default 100), and max_neighbors (max graph connections per node, i.e. HNSW's M, default 16). Larger values → better recall, slower/more memory.
• The chosen space must match what your embedding function expects (most sentence/text embedders are designed for cosine).

Querying

• Query via collection.query(...). Provide either query_texts=["..."] (Chroma embeds via the collection's embedding function) or query_embeddings=[[...]] (required if there is no embedding function; dimensions must match the stored vectors).
• n_results controls how many neighbors to return (default 10).
• Returned fields: ids, documents, distances, metadatas, embeddings. Chroma returns distances, not similarities — "lower distance = more similar." (Mind this: it is the inverse of the cosine similarity from Project 02.)
• Filtering: where filters on metadata; where_document does full-text/regex filtering on the document. Filtering happens alongside the vector search (metadata pre/post-filtering).

Persistence

• A Client() is in-memory (data lost on exit); a PersistentClient(path=...) writes the collection to disk so embeddings survive restarts. Build the index once, reuse it across runs — the "encode once, compare many" property from SBERT made operational.

Relevant To

• concepts: [vector-database, approximate-nearest-neighbor, hnsw, retrieval, distance-vs-similarity, metadata-filtering]
• projects: [03-semantic-search, 04-pdf-research-assistant, 05-personal-memory-system]

Notes

• Distance vs. similarity is a classic bug source. Project 02 ranked by cosine similarity (higher = closer). Chroma ranks by distance (lower = closer). With space="cosine", Chroma's cosine distance ≈ 1 − cosine_similarity. Mixing the two silently inverts rankings.
• Approximate, not exact. HNSW may miss a true nearest neighbor occasionally; for a small lab corpus the difference is invisible, but it is the price of scale. A brute-force cosine scan (Project 02) is the exact baseline to compare against.
• The default space is l2; for text embeddings you almost always want space="cosine" — a deliberate configuration choice, not a default.