Skip to content

Chroma Core: Concepts and APIs

This section is the fastest way to understand Chroma's core data model, client choices, and day-to-day APIs.

If you are new to Chroma, use the path below in order. If you are already building, jump to the API map.

  1. Concepts: Understand tenants, databases, collections, documents, metadata, embeddings, and query flow.
  2. Installation: Install Chroma for local development, server usage, or cloud-connected workflows.
  3. Clients: Pick the right client (PersistentClient, HttpClient, AsyncHttpClient, CloudClient) for your architecture.
  4. Collections: Learn collection lifecycle and core CRUD/query operations.
  5. Filters: Add precise metadata and document filtering to retrieval.
  6. Configuration: Tune index, runtime, and environment options.
  7. Resources: Estimate memory/CPU/disk needs before scaling.
  8. Advanced Search: Learn query-stage semantics, ranking, and execution tradeoffs.

API Map

Client-Level APIs

  • Connect to Chroma: PersistentClient, HttpClient, AsyncHttpClient, CloudClient
  • Scope data isolation: tenant + database selection
  • Perform admin/list operations (for example collection listing and lifecycle actions)

Start in Clients, then use Tenants and Databases for multi-tenant setups.

Collection-Level APIs

  • Create/get collections: create_collection, get_or_create_collection, get_collection
  • Write data: add, upsert, update, delete
  • Read data: get, query, count
  • Manage collection settings: metadata, index configuration, and cloning/forking patterns

Start in Collections, then pair with Filters and Document IDs.

HTTP/OpenAPI Surface

  • Explore server endpoints and OpenAPI: API
  • Generate custom clients when needed

Minimal End-to-End Flow (Python)

import chromadb

client = chromadb.PersistentClient(path="./chroma")
collection = client.get_or_create_collection("quickstart")

collection.upsert(
    ids=["doc-1", "doc-2"],
    documents=["Chroma stores vectors and metadata.", "Filters narrow candidate sets before ranking."],
    metadatas=[{"topic": "basics"}, {"topic": "search"}],
)

result = collection.query(
    query_texts=["How do filters affect retrieval?"],
    where={"topic": "search"},
    n_results=2,
)

print(result["ids"])

Where to Go Next