ChromaDB: Embedded Local Vector Database

1. Architecture of an Embedded Vector Store

While cloud vector databases (like Pinecone) require network round-trips and API credentials,ChromaDB is the "SQLite of vector databases". It runs as an in-process library, eliminating network latency and cloud infrastructure overhead.

2. Installation & Storage Modes

Install the official Python package via pip:

pip install chromadb

ChromaDB supports two primary deployment modes: Ephemeral (in-memory) and Persistent (on-disk):

import chromadb

# Mode A: Ephemeral In-Memory Client (Data disappears when script terminates)
# client = chromadb.EphemeralClient()

# Mode B: Persistent Client (Saves SQLite DB and HNSW index files to disk)
client = chromadb.PersistentClient(path="./my_chroma_db")

print("ChromaDB Heartbeat:", client.heartbeat())

3. Managing Collections & Distance Spaces

A Collection is equivalent to a table in SQL. When creating a collection, you can specify the distance function via the metadata dictionary (cosine, l2, or ip):

# Create or load an existing collection
collection = client.get_or_create_collection(
    name="enterprise_knowledge_base",
    metadata={"hnsw:space": "cosine"}  # "cosine", "l2", or "ip" (Inner Product)
)

print(f"Collection created! Current document count: {collection.count()}")

4. Adding Documents with Rich Metadata

When adding documents, provide unique string ids, raw text documents, and structured metadatas for downstream filtering:

# Batch inserting documents
collection.upsert(
    ids=["doc_1", "doc_2", "doc_3", "doc_4"],
    documents=[
        "Kubernetes pods can be scaled automatically using Horizontal Pod Autoscalers based on CPU thresholds.",
        "PostgreSQL 16 introduced improvements in query parallelism and vacuum performance.",
        "To deploy Docker containers in AWS, use Elastic Container Service (ECS) or EKS.",
        "Python GIL (Global Interpreter Lock) is optional in free-threaded Python 3.13 builds."
    ],
    metadatas=[
        {"category": "devops", "platform": "k8s", "year": 2024},
        {"category": "database", "platform": "postgres", "year": 2023},
        {"category": "devops", "platform": "aws", "year": 2024},
        {"category": "programming", "platform": "python", "year": 2024}
    ]
)

print(f"Successfully upserted records! Total: {collection.count()}")

5. Advanced Metadata Filtering & Search Queries

ChromaDB supports MongoDB-style query operators in its where clause:

# Execute semantic vector search combined with boolean metadata filtering
results = collection.query(
    query_texts=["How do I manage container scaling?"],
    n_results=2,
    where={
        "$and": [
            {"category": {"$eq": "devops"}},
            {"year": {"$gte": 2024}}
        ]
    }
)

print("=== Retrieved Filtered Results ===")
for i in range(len(results["ids"][0])):
    doc_id = results["ids"][0][i]
    document = results["documents"][0][i]
    distance = results["distances"][0][i]
    meta = results["metadatas"][0][i]
    print(f"[{i+1}] ID: {doc_id} | Distance: {distance:.4f}")
    print(f"    Text: {document}")
    print(f"    Meta: {meta}")

6. LangChain RAG Integration

ChromaDB seamlessly wraps into LangChain as a VectorStore retriever for question-answering pipelines:

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

vector_store = Chroma(
    collection_name="enterprise_docs",
    embedding_function=embeddings,
    persist_directory="./chroma_langchain_db"
)

# Convert to retriever
retriever = vector_store.as_retriever(
    search_type="similarity",
    search_kwargs={"k": 3}
)