How to Use 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 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']