chroma-core/chroma

Data infrastructure for AI

Structural Verdict

How Data Flows Through the System

Documents flow through embedding generation, multi-modal indexing, and storage, then similarity search retrieves results by combining vector, text, and metadata queries

1. Ingest — Documents and metadata enter via Client.add() with automatic embedding generation (config: collection.embedding_function, api.batch_size)
2. Index — Embeddings indexed in HNSW, documents in full-text index, metadata in inverted indexes (config: index.hnsw_config, index.fts_enabled)
3. Store — Data written to Arrow-based BlockStore with S3 persistence and WAL durability (config: storage.s3_config, log.retention_policy)
4. Query — Client.query() triggers multi-modal search across vector, text, and metadata indexes (config: query.n_results, query.include_fields)
5. Retrieve — Results merged from all indexes and returned with distances/ranks (config: distance.metric, search.merge_strategy)

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Compaction Loop (scheduled-job, balancing) — Trigger: Block size thresholds or time intervals. Action: Merge small blocks into larger ones for query efficiency. Exit: Target block size achieved.
• Garbage Collection (scheduled-job, balancing) — Trigger: Version retention policies. Action: Clean up unused data versions and files. Exit: Storage quota maintained.
• Index Rebuild (auto-scale, balancing) — Trigger: Index degradation or data drift. Action: Rebuild HNSW index from current data. Exit: Query performance restored.

Delays & Async Processing

• Embedding Generation (async-processing, ~100ms-5s per batch) — Documents unavailable for search until embeddings computed
• Index Sync (eventual-consistency, ~seconds to minutes) — New data may not appear in search results immediately
• S3 Write Latency (async-processing, ~10-100ms) — Data persistence delays
• Cache TTL (cache-ttl, ~configurable) — Index rebuilds when cache expires

Control Points

• Embedding Function (feature-flag) — Controls: Which embedding model processes text documents. Default: default_ef
• HNSW Parameters (threshold) — Controls: Index construction and search quality vs speed tradeoff. Default: M=16, ef_construction=200
• Batch Size (threshold) — Controls: Number of documents processed in single operation. Default: 1000
• Distance Metric (feature-flag) — Controls: Vector similarity calculation method. Default: cosine
• Compaction Trigger (threshold) — Controls: When to merge data blocks for efficiency. Default: size or time based

Package Structure

This monorepo contains 5 packages:

Technology Stack

Key Components

• Client (class) — Main Python client providing the 4-function API (add, query, get, delete) chromadb/__init__.py
• SegmentAPI (class) — Embedded mode implementation handling collections and segments directly chromadb/api/segment.py
• FastAPI (module) — HTTP server providing REST API for client-server mode chromadb/server/fastapi/app.py
• Executor (module) — Query execution engine routing to local or distributed workers rust/frontend/src/executor/mod.rs
• Worker (service) — Distributed worker process handling query execution and indexing rust/worker/src/lib.rs
• BlockStore (service) — Column-oriented storage system for vectors, metadata, and documents rust/blockstore/src/lib.rs
• HnswIndex (class) — HNSW approximate nearest neighbor index for vector similarity search rust/index/src/hnsw/mod.rs
• FullTextIndex (module) — Tantivy-based full-text search index for document content rust/index/src/fulltext/mod.rs
• LogService (service) — Write-ahead log service for durability and replication rust/log-service/src/lib.rs
• SysDB (service) — Metadata catalog storing collection definitions and segment mappings rust/sysdb/src/lib.rs
• GarbageCollector (service) — Background service cleaning up unused data versions and files rust/garbage_collector/src/lib.rs
• EmbeddingFunction (trait) — Abstraction for converting text to embeddings (BM25, Ollama, etc.) rust/chroma/src/embed/mod.rs

Sub-Modules

Configuration

bandit.yaml (yaml)

• exclude_dirs (array, unknown) — default: chromadb/test,bin,build,build,.git,.venv,venv,env,.github,examples,clients/js,.vscode
• tests (array, unknown)
• skips (array, unknown)

docker-compose.server.example.yml (yaml)

• version (string, unknown) — default: 3.9
• networks.net.driver (string, unknown) — default: bridge
• services.server.image (string, unknown) — default: ghcr.io/chroma-core/chroma:latest
• services.server.environment (array, unknown) — default: IS_PERSISTENT=TRUE
• services.server.volumes (array, unknown) — default: chroma-data:/chroma/chroma/
• services.server.ports (array, unknown) — default: 8000:8000
• services.server.networks (array, unknown) — default: net
• volumes.chroma-data.driver (string, unknown) — default: local

docker-compose.test-auth.yml (yaml)

• networks.test_net.driver (string, unknown) — default: bridge
• services.test_server.build.context (string, unknown) — default: .
• services.test_server.build.dockerfile (string, unknown) — default: Dockerfile
• services.test_server.volumes (array, unknown) — default: chroma-data:/chroma/chroma
• services.test_server.command (string, unknown) — default: --workers 1 --host 0.0.0.0 --port 8000 --proxy-headers --log-config chromadb/log_config.yml --timeout-keep-alive 30
• services.test_server.environment (array, unknown) — default: ANONYMIZED_TELEMETRY=False,ALLOW_RESET=True,IS_PERSISTENT=True,CHROMA_SERVER_AUTHN_CREDENTIALS_FILE=${CHROMA_SERVER_AUTHN_CREDENTIALS_FILE},CHROMA_SERVER_AUTHN_CREDENTIALS=${CHROMA_SERVER_AUTHN_CREDENTIALS},CHROMA_SERVER_AUTHN_PROVIDER=${CHROMA_SERVER_AUTHN_PROVIDER},CHROMA_AUTH_TOKEN_TRANSPORT_HEADER=${CHROMA_AUTH_TOKEN_TRANSPORT_HEADER}
• services.test_server.ports (array, unknown) — default: ${CHROMA_PORT:-8000}:8000
• services.test_server.networks (array, unknown) — default: test_net
• +1 more parameters

docker-compose.test.yml (yaml)

• services.test_server.build.context (string, unknown) — default: .
• services.test_server.build.dockerfile (string, unknown) — default: ${DOCKERFILE:-Dockerfile}
• services.test_server.platform (string, unknown) — default: ${PLATFORM:-linux/amd64}
• services.test_server.command (string, unknown) — default: --workers 1 --host 0.0.0.0 --port 8000 --proxy-headers --log-config chromadb/log_config.yml --timeout-keep-alive 30
• services.test_server.environment (array, unknown) — default: ANONYMIZED_TELEMETRY=False,ALLOW_RESET=True,IS_PERSISTENT=True,CHROMA_API_IMPL=chromadb.api.segment.SegmentAPI
• services.test_server.ports (array, unknown) — default: ${CHROMA_PORT:-8000}:8000
• volumes.chroma-data.driver (string, unknown) — default: local

Science Pipeline

1. Document Ingestion — Text strings converted to embeddings via EmbeddingFunction [(batch_size, text) → (batch_size, embedding_dim)] rust/chroma/src/embed/mod.rs
2. Vector Indexing — HNSW index construction from embedding vectors [(n_vectors, embedding_dim) → graph structure] rust/index/src/hnsw/index.rs
3. Block Storage — Column-oriented storage in Arrow format with delta compression [(n_records, n_columns) → compressed blocks] rust/blockstore/src/arrow/block/
4. Similarity Search — HNSW traversal with distance calculations [(query_embedding_dim,) → (k_results, embedding_dim + metadata)] rust/index/src/hnsw/search.rs

Assumptions & Constraints

• [critical] Vector distance functions assume equal-length vectors but no runtime validation enforces this (shape)
• [warning] HNSW index assumes normalized vectors for cosine distance but normalization is optional (value-range)
• [warning] Arrow schema assumes specific column layouts for embeddings (f32 arrays) without schema validation (format)
• [info] Embedding functions assumed to be deterministic and stateless but no enforcement exists (dependency)

Related Fullstack Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.