What's Chroma?

Here is the example code generated by Deepseek; it outlines 4 steps to use Chroma:

import chromadb

# 1, Create a Chroma Client
client = chromadb.Client()

# 2, Create a collection (like a table)
collection = client.create_collection("documents")

# 3, Add embeddings and metadata
collection.add(
    documents=["The sky is blue.", "The grass is green."],
    metadatas=[{"source": "nature"}, {"source": "nature"}],
    ids=["id1", "id2"]
)

# 4, Query for similar items
results = collection.query(
    query_texts=["What color is nature?"],
    n_results=1
)

print(results)

Step1, Create a Chroma Client

There are mainly 3 kinds of Chorma Client:

• In-Memory Client: Ideal for testing, quick experiments, or when you don't need data persistence. Data is lost when the program ends.
• Persistent Client: Stores your data on disk, so it's saved between sessions. This is suitable for local development or smaller-scale applications where you manage the data directly on your machine.
• HTTP Client (Client-Server Mode): Connects to a separate Chroma server process. This is the most scalable and production-ready option, allowing your application to interact with a remote or horizontally scaled ChromaDB instance.

1, In-memory ephemeral client (for testing or simple use):

import chromadb

client = chromadb.Client()

2, Persistent client (stores data on disk):

import chromadb

client = chromadb.PersistentClient(path="/path/to/save/to")

If you create a chromadb.PersistentClient pointing to a path that already contains existing data, the client will load and use the existing database stored at that location rather than overwriting or deleting it.

3, HTTP client (connects to a separate Chroma server):

import chromadb

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

Step2, Creat a Collection

Collections are where you'll store your embeddings, documents, and any additional metadata. Collections index your embeddings and documents, and enable efficient retrieval and filtering. You can create a collection with a name:

collection = chroma_client.create_collection(name="my_collection")

Often, you'll want to create a collection if it doesn't exist, but retrieve it if it does. This prevents errors if you run your code multiple times. Use get_or_create_collection() for this:

collection = chroma_client.get_or_create_collection(name="my_collection")

You can also set the Metadata for the collection:

collection = client.get_or_create_collection(
    name="my_collection",
    metadata={"description": "my test collection"}
)

Step3, Add Text Documents to the Collection

Chroma works with lists of strings (your text documents), optional metadata for each document (as a dictionary), and unique IDs for each document. Chroma will automatically handle tokenization and embedding if you don't provide pre-computed embeddings.

documents_to_add = [
    "This is the first document about nature.",
    "The second document discusses technology advancements.",
    "A third document explores historical events.",
    "This is a document about plants and animals."
]

metadatas = [
    {"source": "nature_blog", "category": "nature"},
    {"source": "tech_news", "category": "technology"},
    {"source": "history_book", "category": "history"},
    {"source": "nature_magazine", "category": "nature"}
]

ids_to_add = ["doc1", "doc2", "doc3", "doc4"]

# Add Documents to the Collection: Use the add() method of your collection.
collection.add(
    documents=documents_to_add,
    metadatas=metadatas,
    ids=ids_to_add
)

Chroma will automatically embed the documents using the collection's embedding function (it uses a default if you don't specify one when creating the collection). You can also use Ollama embedding model:

import chromadb
from chromadb.utils import embedding_functions

# Define Ollama embedding function
ollama_ef = embedding_functions.OllamaEmbeddingFunction(
    model_name="nomic-embed-text",
    url="http://localhost:11434/api/embeddings"  # Ollama's default API endpoint
)

# Initialize Chroma client
client = chromadb.Client()

# Create a collection with Ollama embeddings
collection = client.create_collection(
    name="documents",
    embedding_function=ollama_ef,
)

# Add documents
collection.add(
    documents=["AI is changing the world", "Chroma is a vector database"],
    ids=["doc1", "doc2"],
)

# Query
results = collection.query(
    query_texts=["What is Chroma?"],
    n_results=1
)

print(results)

Step4, Query the Collection

To query a Chroma collection in Python, you use the collection.query() method, which performs a vector similarity search based on embeddings of your query texts. Here’s how it works and how to use it:

collection.query(
    query_texts=["your query text"],
    n_results=3
)

The query() method returns a dictionary with keys:

• "ids": Matching document IDs per query
• "documents": Matching documents per query
• "distances": Similarity scores (lower = closer)
• "metadatas": Optional metadata if stored
• "embeddings": Returned if include=['embeddings']