ChromaDB Tutorial: The Complete Beginner's Guide (2026)

ChromaDB is the fastest way to add vector search to a Python application. It runs entirely in-process — no Docker container, no cloud account, no server to manage. You pip install chromadb, write five lines of Python, and you have a working vector database.

That simplicity makes ChromaDB the standard starting point for learning vector databases and the go-to choice for RAG prototypes and small-to-medium production deployments. This tutorial covers everything you need: collections, embedding functions, metadata filtering, persistence, updates, deletions, and building a real document search pipeline.

If you are new to vector databases, read What is a Vector Database? first — this tutorial assumes you understand what embeddings and similarity search are.

Installing ChromaDB

bash

pip install chromadb

For sentence-transformers (the free local embedding model used in most examples below):

bash

pip install chromadb sentence-transformers

ChromaDB requires Python 3.8 or later. All examples in this tutorial were tested on Python 3.11.

ChromaDB Client Modes

ChromaDB has three operating modes:

Ephemeral (in-memory) — data exists only for the lifetime of your Python process. Fastest, but nothing is saved to disk. Useful for unit tests and quick experiments.

python

import chromadb

client = chromadb.EphemeralClient()

Persistent (local disk) — data is saved to a directory on disk and survives process restarts. The standard mode for development and small deployments.

python

client = chromadb.PersistentClient(path="./chroma_data")

HTTP Client — connects to a separately running ChromaDB server (started with chroma run --path ./chroma_data). Used when multiple processes or services need to share the same vector database.

python

client = chromadb.HttpClient(host="localhost", port=8000)

For this tutorial, use PersistentClient — it behaves identically to a production setup but requires no separate service.

Collections: ChromaDB's Core Concept

In ChromaDB, a collection is the equivalent of a table in SQL. It stores:

Documents: the raw text (or other content) you want to search
Embeddings: the vector representations of those documents
Metadata: structured key-value pairs associated with each document
IDs: a unique string identifier for each item

You can have multiple collections in a single client, each with its own embedding function and distance metric.

python

import chromadb

client = chromadb.PersistentClient(path="./chroma_data")

# Create a collection
collection = client.create_collection(name="my_documents")

# Get an existing collection (raises error if it doesn't exist)
collection = client.get_collection(name="my_documents")

# Get or create — the safest option for application code
collection = client.get_or_create_collection(name="my_documents")

# List all collections
print(client.list_collections())

# Delete a collection
client.delete_collection(name="my_documents")

Embedding Functions

An embedding function tells ChromaDB how to convert your documents into vector embeddings. ChromaDB ships with built-in support for several providers.

Option 1: Sentence Transformers (Free, Local)

The default and most convenient option for most use cases. The model downloads once (~80 MB) and then runs entirely offline.

python

from chromadb.utils import embedding_functions

ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"   # 384 dimensions, fast, good quality
)

collection = client.get_or_create_collection(
    name="docs",
    embedding_function=ef,
    metadata={"hnsw:space": "cosine"}
)

Popular sentence-transformer models for different use cases:

Model	Dimensions	Speed	Use Case
`all-MiniLM-L6-v2`	384	Very fast	General text, best starting point
`all-mpnet-base-v2`	768	Moderate	Higher quality general text
`multi-qa-MiniLM-L6-cos-v1`	384	Very fast	Question/answer retrieval
`paraphrase-multilingual-MiniLM-L12-v2`	384	Fast	Multilingual support

Option 2: OpenAI Embeddings

Higher quality embeddings, especially for domain-specific content, at a cost per token.

python

ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-openai-api-key",
    model_name="text-embedding-3-small"   # 1536 dimensions
)

Option 3: Custom Embedding Function

Wrap any model — Cohere, Anthropic, a local GGUF model — by subclassing EmbeddingFunction:

python

from chromadb import EmbeddingFunction, Documents, Embeddings

class MyEmbeddingFunction(EmbeddingFunction):
    def __call__(self, input: Documents) -> Embeddings:
        # Call your model, return list of float lists
        return my_model.encode(input).tolist()

collection = client.get_or_create_collection(
    name="custom",
    embedding_function=MyEmbeddingFunction()
)

Lock Your Embedding Function

Once you add documents to a collection, you must always use the same embedding function to query it. Changing the model invalidates all existing embeddings. If you need to switch models, create a new collection and re-embed all documents.

Distance Metrics

Set the distance metric at collection creation time via the metadata parameter:

python

# Cosine similarity (default for text — recommended)
collection = client.get_or_create_collection(
    name="text_docs",
    metadata={"hnsw:space": "cosine"}
)

# L2 (Euclidean distance — common for images)
collection = client.get_or_create_collection(
    name="image_docs",
    metadata={"hnsw:space": "l2"}
)

# Inner product / dot product (for normalised vectors)
collection = client.get_or_create_collection(
    name="ip_docs",
    metadata={"hnsw:space": "ip"}
)

For text: always use cosine. For image embeddings from models like CLIP: l2 or ip depending on whether the model normalises its outputs.

Adding Documents

python

from chromadb.utils import embedding_functions

client = chromadb.PersistentClient(path="./chroma_data")
ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_or_create_collection(
    name="support_kb",
    embedding_function=ef,
    metadata={"hnsw:space": "cosine"}
)

# Add documents — ChromaDB embeds them automatically
collection.add(
    ids=["doc_001", "doc_002", "doc_003", "doc_004", "doc_005"],
    documents=[
        "How to reset your password if you are locked out",
        "Device fails to boot following a software patch",
        "Cancel your subscription before the renewal date",
        "How to export your invoice history as a PDF",
        "Battery drains faster than expected after the update",
    ],
    metadatas=[
        {"category": "account", "priority": "high"},
        {"category": "hardware", "priority": "high"},
        {"category": "billing", "priority": "medium"},
        {"category": "billing", "priority": "low"},
        {"category": "hardware", "priority": "medium"},
    ]
)

print(f"Added {collection.count()} documents")

IDs must be unique strings. If you call add() with an ID that already exists, ChromaDB raises an error. Use upsert() instead when you are not sure whether a document already exists.

Providing Pre-computed Embeddings

If you have already computed embeddings outside ChromaDB (e.g., in a batch preprocessing job), pass them directly:

python

import numpy as np

# Pre-computed embeddings — shape (n_docs, embedding_dim)
embeddings = np.random.rand(3, 384).tolist()   # placeholder

collection.add(
    ids=["pre_001", "pre_002", "pre_003"],
    embeddings=embeddings,
    documents=["raw text 1", "raw text 2", "raw text 3"]
)

When you provide embeddings directly, ChromaDB does not call the collection's embedding function for those documents.

Querying: The Core Operation

python

results = collection.query(
    query_texts=["my laptop won't start after the Windows update"],
    n_results=3,
    include=["documents", "distances", "metadatas"]
)

for doc, dist, meta in zip(
    results["documents"][0],
    results["distances"][0],
    results["metadatas"][0]
):
    similarity = 1 - dist   # cosine distance → similarity
    print(f"[{similarity:.3f}] [{meta['category']}] {doc}")

Output:

[0.851] [hardware] Device fails to boot following a software patch
[0.734] [hardware] Battery drains faster than expected after the update
[0.581] [account] How to reset your password if you are locked out

The results dictionary always has this shape. results["documents"] is a list of lists — one inner list per query. If you pass multiple queries at once:

python

results = collection.query(
    query_texts=[
        "can't log in to my account",
        "charge not lasting as long as before"
    ],
    n_results=2
)
# results["documents"][0] → top 2 for first query
# results["documents"][1] → top 2 for second query

What can you include in results?

The include parameter controls what ChromaDB returns:

"documents" — original text
"embeddings" — raw vector arrays
"distances" — similarity scores
"metadatas" — metadata dictionaries
"uris" — URIs if you stored them
"data" — raw data if multi-modal

Distance vs Similarity

ChromaDB returns distances, not similarity scores. For cosine distance: similarity = 1 - distance. A distance of 0.0 means identical; 2.0 means opposite. For L2 distance, smaller is more similar — there is no simple normalisation to a 0–1 similarity score.

Metadata Filtering

Metadata filters let you combine vector similarity search with structured constraints. This is one of ChromaDB's most powerful features.

Basic Filters

python

# Only search within the billing category
results = collection.query(
    query_texts=["will I be charged if I don't cancel?"],
    n_results=2,
    where={"category": "billing"}
)

Operators

ChromaDB supports a rich set of filter operators via the $ prefix:

python

# Equality
where={"category": {"$eq": "billing"}}

# Not equal
where={"category": {"$ne": "hardware"}}

# Greater than / less than
where={"priority_score": {"$gt": 5}}
where={"priority_score": {"$lte": 10}}

# In a list of values
where={"category": {"$in": ["billing", "account"]}}

# Not in a list
where={"category": {"$nin": ["hardware"]}}

Boolean Logic: $and, $or

python

# Must be billing category AND high priority
results = collection.query(
    query_texts=["charge for next year"],
    n_results=3,
    where={
        "$and": [
            {"category": {"$eq": "billing"}},
            {"priority": {"$eq": "high"}}
        ]
    }
)

# Either billing OR account
results = collection.query(
    query_texts=["login and payment issue"],
    n_results=3,
    where={
        "$or": [
            {"category": {"$eq": "billing"}},
            {"category": {"$eq": "account"}}
        ]
    }
)

Full-Text Filter: $contains

python

# Filter on document content (keyword match, not semantic)
results = collection.query(
    query_texts=["account access"],
    n_results=3,
    where_document={"$contains": "password"}
)

where_document filters on the actual document text, while where filters on metadata. Both can be used together in the same query.

CRUD Operations: Update and Delete

Upsert (Insert or Update)

upsert() inserts new documents or updates existing ones — the safest choice for most ingestion pipelines:

python

collection.upsert(
    ids=["doc_001"],
    documents=["How to reset your password, PIN, or security questions"],
    metadatas=[{"category": "account", "priority": "high", "version": 2}]
)

Update

update() modifies existing documents. It raises an error if an ID does not exist:

python

collection.update(
    ids=["doc_003"],
    documents=["Cancel your subscription at any time from the billing dashboard"],
    metadatas=[{"category": "billing", "priority": "medium", "updated": "2026-04"}]
)

You can update documents, metadatas, or embeddings independently — you do not need to provide all three.

Get by ID

python

# Fetch specific documents by ID
result = collection.get(
    ids=["doc_001", "doc_002"],
    include=["documents", "metadatas"]
)
print(result["documents"])

Delete

python

# Delete by ID
collection.delete(ids=["doc_004"])

# Delete by metadata filter
collection.delete(where={"category": "hardware"})

# Delete by document content
collection.delete(where_document={"$contains": "password"})

Deletions are Permanent

ChromaDB does not have a recycle bin or soft-delete. Deleted items are gone immediately. For production systems where auditability matters, consider soft-deleting by updating a metadata field (e.g., status: 'deleted') and filtering it out in queries, while keeping the actual record.

Inspecting and Managing Collections

python

# Count documents
print(collection.count())   # 4

# Get all documents (use with care on large collections)
all_docs = collection.get(include=["documents", "metadatas"])
for id_, doc, meta in zip(
    all_docs["ids"],
    all_docs["documents"],
    all_docs["metadatas"]
):
    print(f"{id_}: [{meta['category']}] {doc[:60]}")

# Peek at first 5 documents
print(collection.peek(5))

Building a Document Search Pipeline

Here is a complete, production-style document ingestion and query pipeline — the kind you would use in a RAG application.

python

import chromadb
from chromadb.utils import embedding_functions
from pathlib import Path
import hashlib

class DocumentSearchPipeline:
    """
    A simple document ingestion and semantic search pipeline built on ChromaDB.
    Uses SHA-256 of the document text as a stable ID to support idempotent upserts.
    """

    def __init__(self, persist_path: str = "./search_db"):
        self.client = chromadb.PersistentClient(path=persist_path)
        self.ef = embedding_functions.SentenceTransformerEmbeddingFunction(
            model_name="all-MiniLM-L6-v2"
        )
        self.collection = self.client.get_or_create_collection(
            name="documents",
            embedding_function=self.ef,
            metadata={"hnsw:space": "cosine"}
        )

    def _make_id(self, text: str) -> str:
        """Generate a stable ID from document content."""
        return hashlib.sha256(text.encode()).hexdigest()[:16]

    def ingest(self, documents: list[dict]) -> int:
        """
        Ingest a list of {'text': str, 'metadata': dict} dicts.
        Uses upsert so re-ingestion is safe.
        """
        ids = [self._make_id(doc["text"]) for doc in documents]
        texts = [doc["text"] for doc in documents]
        metas = [doc.get("metadata", {}) for doc in documents]

        self.collection.upsert(ids=ids, documents=texts, metadatas=metas)
        return len(documents)

    def search(
        self,
        query: str,
        n_results: int = 5,
        filters: dict | None = None
    ) -> list[dict]:
        """
        Run a semantic search.
        Returns a list of results sorted by similarity (highest first).
        """
        kwargs = {
            "query_texts": [query],
            "n_results": min(n_results, self.collection.count()),
            "include": ["documents", "distances", "metadatas"],
        }
        if filters:
            kwargs["where"] = filters

        results = self.collection.query(**kwargs)

        return [
            {
                "text": doc,
                "similarity": round(1 - dist, 4),
                "metadata": meta,
            }
            for doc, dist, meta in zip(
                results["documents"][0],
                results["distances"][0],
                results["metadatas"][0],
            )
        ]

    def stats(self) -> dict:
        return {"total_documents": self.collection.count()}


# --- Usage ---

pipeline = DocumentSearchPipeline()

# Ingest documents
pipeline.ingest([
    {"text": "How to reset your password if locked out", "metadata": {"source": "kb", "category": "account"}},
    {"text": "Device fails to boot after a firmware update", "metadata": {"source": "kb", "category": "hardware"}},
    {"text": "Cancel your subscription before the renewal date", "metadata": {"source": "kb", "category": "billing"}},
    {"text": "Export your invoice history as a CSV or PDF", "metadata": {"source": "kb", "category": "billing"}},
    {"text": "Battery drains faster after the latest OS update", "metadata": {"source": "kb", "category": "hardware"}},
    {"text": "How to transfer your licence to a new device", "metadata": {"source": "kb", "category": "account"}},
])

print(pipeline.stats())

# Semantic search — no metadata filter
print("\n--- General search ---")
for r in pipeline.search("my laptop stopped working after an update", n_results=3):
    print(f"[{r['similarity']}] [{r['metadata']['category']}] {r['text']}")

# Semantic search scoped to billing only
print("\n--- Billing search ---")
for r in pipeline.search("charges on my account", n_results=3, filters={"category": "billing"}):
    print(f"[{r['similarity']}] {r['text']}")

ChromaDB with LangChain and LlamaIndex

ChromaDB has first-class integrations with both major RAG frameworks.

LangChain:

python

from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")

vectorstore = Chroma(
    collection_name="langchain_docs",
    embedding_function=embeddings,
    persist_directory="./langchain_chroma"
)

# Add documents
vectorstore.add_texts(
    texts=["Doc 1 content", "Doc 2 content"],
    metadatas=[{"source": "file1.pdf"}, {"source": "file2.pdf"}]
)

# Similarity search
docs = vectorstore.similarity_search("query text", k=3)

LlamaIndex:

python

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import VectorStoreIndex, StorageContext

chroma_client = chromadb.PersistentClient(path="./llamaindex_chroma")
chroma_collection = chroma_client.get_or_create_collection("llamaindex_docs")

vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
query_engine = index.as_query_engine()
response = query_engine.query("What does the document say about X?")

HNSW Index Tuning

ChromaDB uses HNSW internally. For most use cases the defaults are fine. For large collections or when you need to optimise recall vs speed, tune the HNSW parameters at collection creation:

python

collection = client.get_or_create_collection(
    name="large_collection",
    metadata={
        "hnsw:space": "cosine",
        "hnsw:construction_ef": 200,   # higher = better recall, slower indexing (default: 100)
        "hnsw:search_ef": 100,         # higher = better recall, slower queries (default: 10)
        "hnsw:M": 16,                  # connections per node, affects memory (default: 16)
        "hnsw:batch_size": 1000,       # docs per batch during indexing
        "hnsw:sync_threshold": 1000,   # batch size before index sync to disk
    }
)

When to Tune HNSW

The defaults work well for collections under 100,000 documents. If you notice queries returning obviously poor results (low recall), increase hnsw:search_ef first — it costs query time but improves result quality. Increase hnsw:construction_ef only if you are accepting poor recalls even at query time, as it only affects indexing.

Key Takeaways

ChromaDB runs entirely in-process — no server, no Docker, no cloud account needed for development
Use PersistentClient for development and small production deployments; HttpClient when multiple services share one database
The embedding function must stay consistent — adding and querying must use the same model
Use cosine distance for all text-based collections
Combine vector search with metadata filters using the where parameter for scoped queries
Use upsert() rather than add() in production ingestion pipelines to handle re-runs safely
HNSW parameters can be tuned for recall vs speed trade-offs on large collections

What's Next in the Vector Database Series

Next post: ChromaDB vs Pinecone vs pgvector: Which Vector Database Should You Use?
Coming up: Build a Semantic Search Engine from Scratch
Advanced: Vector Database Optimisation for Production

This post is part of the Vector Database Series. Previous post: What is a Vector Database? The Complete Beginner's Guide.