Vector Chroma

Chroma is an open-source vector database designed for simplicity. Developers often choose it for first projects, prototypes, and small AI applications because it needs very little setup. A few lines of Python give you a working search system.

Why Chroma Feels Easy

Many vector tools ask you to create embeddings yourself, define schemas, and configure indexes. Chroma removes most of that work. You hand it text, and it can create the embeddings through a default embedding function.

CHROMA WORKFLOW

  Your text documents
          |
          v
  +------------------------+
  | Chroma                 |
  |  - creates embeddings  |
  |  - stores vectors      |
  |  - stores documents    |
  |  - stores metadata     |
  +------------------------+
          |
          v
  Search by plain-language question

Core Concepts

Client: The connection to Chroma. It can run in memory, save to disk, or connect to a server.
Collection: A named group of documents, similar to a folder.
Document: The original text you want to search.
Metadata: A dictionary of facts about a document, such as author or year.
ID: A unique string that identifies each document.

A Complete First Example

import chromadb

client = chromadb.Client()

collection = client.create_collection(name="notes")

collection.add(
    ids=["n1", "n2", "n3"],
    documents=[
        "Pack light clothes for a beach holiday",
        "Whisk eggs and sugar until fluffy",
        "Book flights early to save money on travel",
    ],
    metadatas=[
        {"topic": "travel"},
        {"topic": "cooking"},
        {"topic": "travel"},
    ],
)

results = collection.query(
    query_texts=["How do I prepare for a trip?"],
    n_results=2,
)

The query never mentions "beach" or "flights". Chroma still returns the two travel notes because their meaning sits close to the question.

Reading the Results

results = {
  "ids":       [["n1", "n3"]],
  "documents": [["Pack light clothes...", "Book flights early..."]],
  "distances": [[0.52, 0.61]],
  "metadatas": [[{"topic": "travel"}, {"topic": "travel"}]]
}

Lower distance = closer match

The results use nested lists because Chroma accepts several queries in one call. Each inner list belongs to one query.

Filtering by Metadata

collection.query(
    query_texts=["saving money"],
    n_results=2,
    where={"topic": "travel"},
)

The where option limits the search to documents whose metadata matches. Use it to separate categories, languages, or authors.

Storage Modes

Mode	How It Works	Best For
In-memory	Data disappears when the program ends	Experiments and tests
Persistent	Data saves to a folder on disk	Personal and small projects
Client and server	A separate Chroma server handles requests	Shared team use

Using Your Own Embeddings

You can skip the default embedding function and supply vectors directly. This option helps when you want a specific embedding model.

collection.add(
    ids=["a1"],
    embeddings=[[0.1, 0.9, 0.3]],
    documents=["Original text here"],
)

Remember the golden rule: use the same embedding method for stored documents and for queries.

Strengths and Limits

Strengths	Limits
Very fast to learn	Fewer advanced tuning controls than larger platforms
Works well with popular AI frameworks	Large production workloads need careful testing
Stores text, vectors, and metadata together	Fewer deployment options than enterprise-focused tools
Free and open source	You manage hosting and backups yourself

Good Use Cases

Learning vector search for the first time.
Building a question-answering demo over a few hundred documents.
Testing a retrieval idea before choosing a production database.
Adding private document search to a personal project.

Chroma lowers the barrier to entry. Start here to understand how collections, embeddings, and queries fit together, then evaluate larger platforms once your data and traffic grow.

Previous lesson

Back to course

Next lesson