/api-vector-db-chroma

name: api-vector-db-chroma
description: Chroma vector database -- collection management, automatic embedding, metadata filtering, document storage, query patterns

Chroma Patterns

> **Quick Guide:** Use `chromadb` (v3.x) with `@chroma-core/default-embed` for automatic embedding. Chroma auto-embeds documents if no embeddings are provided -- just pass `documents` and `ids` to `collection.add()`. Use `where` for metadata filtering and `whereDocument` for document content filtering (`$contains`, `$regex`). Default distance metric is `l2` (Euclidean); use `cosine` for most embedding models via `configuration: { hnsw: { space: "cosine" } }`. Query results return nested arrays (`ids: string[][]`) because queries are batched -- always access `results.ids[0]` for a single query. Include only the fields you need via the `include` parameter to reduce payload size.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST install `@chroma-core/default-embed` alongside `chromadb` -- the default embedding function ships as a separate package since v3)**

**(You MUST access query results as nested arrays -- `results.ids[0]`, `results.documents[0]` -- because Chroma batches queries and returns `string[][]` not `string[]`)**

**(You MUST use the `configuration` parameter for HNSW settings -- the legacy `metadata: { "hnsw:space": "cosine" }` approach is deprecated)**

**(You MUST use flat metadata values only (string, number, boolean, typed arrays) -- nested objects are not supported and will be rejected)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) -- Client setup, collection management, add, query, get, update, upsert, delete
• [Metadata Filtering](examples/metadata-filtering.md) -- Filter operators, compound filters, document content filters, whereDocument
• [Embedding Functions](examples/embedding-functions.md) -- Default, OpenAI, custom embedding functions, provider packages

**Additional resources:**

• [reference.md](reference.md) -- API quick reference, filter operators, include options, limits, production checklist

---

**Auto-detection:** Chroma, chromadb, ChromaClient, CloudClient, createCollection, getOrCreateCollection, collection.add, collection.query, collection.get, collection.upsert, queryTexts, queryEmbeddings, nResults, whereDocument, $contains, @chroma-core/default-embed, @chroma-core/openai, EmbeddingFunction, vector database, semantic search, embedding, RAG retrieval, hnsw:space

**When to use:**

• Semantic search over document embeddings (RAG retrieval)
• Rapid prototyping with automatic embedding generation (no external embedding pipeline needed)
• Metadata-filtered vector search with compound logical operators
• Document content filtering with `$contains` and `$regex`
• Local development with in-process or Docker-based Chroma server

**Key patterns covered:**

• Client setup (HTTP, Cloud, Docker)
• Collection management (create, get, delete, configure HNSW)
• Document CRUD with automatic embedding (add, query, get, update, upsert, delete)
• Metadata filtering (`where`) with comparison, set, array, and logical operators
• Document content filtering (`whereDocument`) with `$contains` and `$regex`
• Embedding function configuration (default, OpenAI, custom)
• Query result handling (nested array structure, include options)

**When NOT to use:**

• Full-text search with complex boolean ranking (use a dedicated search engine)
• Relational data with joins and transactions (use a relational database)
• Multi-modal image+text embeddings in TypeScript (currently Python-only in Chroma)
• High-scale production with millions of vectors and strict SLAs (evaluate managed vector databases)

---

<philosophy>

Philosophy

Chroma is a **lightweight, developer-friendly embedding database** designed for rapid prototyping and production RAG applications. The core principle: **pass documents in, get relevant results out -- Chroma handles embedding automatically.**

**Core principles:**

1. **Documents first, vectors optional** -- Unlike most vector databases, Chroma can embed documents automatically using a configured embedding function. You never need to manage embeddings directly unless you want to. 2. **Collections are self-contained** -- Each collection has its own embedding function, distance metric, and HNSW configuration. No global index management needed. 3. **Metadata is for filtering, documents are for content** -- Use `where` for structured metadata filters and `whereDocument` for full-text content filters. Both can be combined in a single query. 4. **Batteries included** -- The default embedding function (`all-MiniLM-L6-v2` via `@chroma-core/default-embed`) works out of the box for English text. Swap to OpenAI, Cohere, or any provider with a single package change. 5. **Query results are batched** -- Chroma supports multiple queries in a single call. Results are always nested arrays (`string[][]`), even for single queries. Always access `[0]` for the first query's results.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Initialization

Always pass the server URL explicitly from an environment variable -- never rely on the implicit `http://localhost:8000` default. See [examples/core.md](examples/core.md) for HTTP, Cloud, and token-authenticated client examples.

const chromaUrl = process.env.CHROMA_URL;
if (!chromaUrl) throw new Error("CHROMA_URL environment variable is required");
return new ChromaClient({ path: chromaUrl });

---

Pattern 2: Collection with Distance Metric

Use the `configuration` parameter for HNSW settings -- never the deprecated `metadata: { "hnsw:space": "cosine" }` approach. See [examples/core.md](examples/core.md).

const collection = await client.createCollection({
  name: COLLECTION_NAME,
  configuration: { hnsw: { space: "cosine" } },
});

---

Pattern 3: Add Documents with Automatic Embedding

Pass `documents` and `ids`