eliferjunior/chromadb

ChromaDB

Overview

ChromaDB is an open-source vector database for storing, searching, and managing embeddings. It provides a simple API for document ingestion, semantic similarity search, and metadata filtering, supporting both Python and JavaScript/TypeScript clients with embedded, server, and cloud deployment options.

Instructions

• When initializing, use get_or_create_collection for idempotent collection setup, choose PersistentClient for development and HttpClient for production server connections.
• When adding documents, batch add() calls in chunks of 5,000 documents, always store source metadata (filename, URL, page number) for RAG citations, and use upsert() for incremental updates to avoid duplicates.
• When querying, use collection.query(query_texts=..., n_results=...) for text-based search, combine metadata where filters to narrow results before semantic search, and set n_results based on the LLM's context window (5-10 for most RAG pipelines).
• When choosing embeddings, use the default Sentence Transformers for local development without API keys, OpenAI or Cohere embedding functions for production, or pass pre-computed vectors directly.
• When filtering metadata, use operators like $eq, $gt, $in with $and/$or logical operators, and combine with where_document for content-based filtering alongside semantic similarity.
• When deploying, use the embedded PersistentClient for single-node applications, Docker for server mode, or Chroma Cloud for managed hosting with multi-tenancy support.
• When tuning performance, configure HNSW parameters (hnsw:M, hnsw:construction_ef, hnsw:search_ef) for the quality-speed tradeoff and choose cosine distance for normalized embeddings (OpenAI, Cohere).

Examples

Example 1: Build a document Q&A pipeline

User request: "Set up a RAG pipeline with ChromaDB for answering questions about our docs"

Actions:

1. Load documents and split into chunks with metadata (source, page)
2. Create a collection with OpenAI embedding function
3. Batch-add document chunks with upsert() for idempotent ingestion
4. Query with collection.query() and pass retrieved chunks as context to the LLM

Output: A semantic search pipeline that retrieves relevant document chunks for LLM-powered Q&A.

Example 2: Add filtered semantic search to an application

User request: "Implement product search that combines text similarity with category filters"

Actions:

1. Create a collection with product descriptions and category metadata
2. Implement search combining query_texts with where={"category": "electronics"}
3. Return results with distances for relevance ranking
4. Add price range filtering with $gte and $lte operators

Output: A filtered semantic search that narrows by metadata before ranking by text similarity.

Guidelines

• Use get_or_create_collection for idempotent collection initialization; it is safe for restarts.
• Batch add() calls in chunks of 5,000 documents to manage memory usage.
• Always store source metadata (filename, URL, page number); it is essential for RAG citations.
• Use upsert() for incremental updates to avoid duplicate documents when re-ingesting.
• Set n_results based on the LLM's context window: 5-10 results for most RAG pipelines.
• Use metadata filtering to narrow results before semantic search to reduce noise.
• Choose cosine distance for normalized embeddings (OpenAI, Cohere) and l2 for unnormalized.