ChromaEmbeddingStore API

The primary class for interacting with Chroma vector database.

package dev.langchain4j.store.embedding.chroma;

public class ChromaEmbeddingStore implements dev.langchain4j.store.embedding.EmbeddingStore<TextSegment>

Implements the LangChain4j EmbeddingStore interface providing full CRUD operations for vector embeddings with metadata support.

Construction

Builder (Recommended)

public static Builder builder();

Returns a builder for configuring and creating ChromaEmbeddingStore instances.

Example:

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("my-documents")
    .build();

See: Builder API

Deprecated Constructor

@Deprecated(since = "1.7.0-beta13", forRemoval = true)
public ChromaEmbeddingStore(
    String baseUrl,
    String collectionName,
    java.time.Duration timeout,
    boolean logRequests,
    boolean logResponses
);

Deprecated - use builder instead. Only supports V1 API.

Add Methods

Add Single Embedding

public String add(Embedding embedding);

Adds an embedding with auto-generated ID.

Parameters:

• embedding - the embedding vector to add

Returns: auto-generated UUID string

Example:

Embedding emb = Embedding.from(new float[]{0.1f, 0.2f, 0.3f});
String id = store.add(emb);

public void add(String id, Embedding embedding);

Adds an embedding with specific ID.

Parameters:

• id - custom ID for the embedding
• embedding - the embedding vector to add

Returns: void

Example:

store.add("custom-123", embedding);

public String add(Embedding embedding, TextSegment textSegment);

Adds an embedding with associated text segment.

Parameters:

• embedding - the embedding vector
• textSegment - text content and metadata (may be null)

Returns: auto-generated UUID string

Example:

TextSegment segment = TextSegment.from("document text");
String id = store.add(embedding, segment);

Add Multiple Embeddings

public List<String> addAll(List<Embedding> embeddings);

Adds multiple embeddings with auto-generated IDs.

Parameters:

• embeddings - list of embeddings to add

Returns: list of auto-generated UUIDs

Example:

List<String> ids = store.addAll(embeddings);

public void addAll(
    List<String> ids,
    List<Embedding> embeddings,
    List<TextSegment> textSegments
);

Adds multiple embeddings with custom IDs and text segments.

Parameters:

• ids - custom IDs (must match embeddings size)
• embeddings - list of embeddings
• textSegments - list of text segments (may be null)

Returns: void

Example:

store.addAll(ids, embeddings, segments);

default List<String> addAll(
    List<Embedding> embeddings,
    List<TextSegment> embedded
);

Inherited default method - adds embeddings with text segments and auto-generated IDs.

Search Method

public EmbeddingSearchResult<TextSegment> search(EmbeddingSearchRequest request);

Searches for similar embeddings using cosine similarity.

Parameters:

• request - search request with query embedding and parameters

Returns: search result with matching embeddings and scores

Example:

EmbeddingSearchRequest req = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmb)
    .maxResults(10)
    .minScore(0.7)
    .build();

EmbeddingSearchResult<TextSegment> result = store.search(req);

See: Search Types API

Remove Methods

Remove Single

default void remove(String id);

Removes a single embedding by ID (default interface implementation).

Parameters:

• id - embedding ID to remove

Returns: void

Example:

store.remove("embedding-id");

Remove Multiple by IDs

public void removeAll(java.util.Collection<String> ids);

Removes multiple embeddings by IDs.

Parameters:

• ids - collection of IDs to remove

Returns: void

Example:

store.removeAll(Arrays.asList("id1", "id2", "id3"));

Remove by Filter

public void removeAll(Filter filter);

Removes embeddings matching metadata filter.

Parameters:

• filter - metadata filter condition

Returns: void

Example:

Filter f = metadataKey("status").isEqualTo("archived");
store.removeAll(f);

See: Filter API

Remove All

public void removeAll();

Removes all embeddings from the collection.

Implementation: Deletes and recreates the collection.

Warning: This is destructive and cannot be undone.

Example:

store.removeAll();  // Clear entire collection

Observability Methods

@Experimental
default EmbeddingStore<TextSegment> addListener(EmbeddingStoreListener listener);

Wraps the store with an observability listener (experimental, since 1.11.0).

Parameters:

• listener - listener for store events

Returns: wrapped store with listener

@Experimental
default EmbeddingStore<TextSegment> addListeners(List<EmbeddingStoreListener> listeners);

Wraps the store with multiple observability listeners (experimental, since 1.11.0).

Parameters:

• listeners - list of listeners

Returns: wrapped store with listeners

Characteristics

Distance Metric

Always cosine distance:

• HNSW configuration: space = cosine
• Cannot be changed

Score Calculation

distance ∈ [0, 2]
score = 1 - (distance / 2)
score ∈ [0, 1]

Where:

• score = 1.0 - perfect match (identical vectors)
• score = 0.5 - orthogonal vectors
• score = 0.0 - opposite vectors

Auto-Creation

Collections are automatically created if they don't exist when the store is instantiated.

V2 API: Tenants and databases are also auto-created.

Thread Safety

Not guaranteed - users should synchronize access if using from multiple threads.

Implementation Notes

Collection Management

• Collection is created on first store instantiation if it doesn't exist
• removeAll() deletes and recreates the collection
• Collection name, distance metric, and other settings are preserved

ID Generation

Auto-generated IDs are UUIDs in string format.

Batch Operations

Batch methods (addAll, removeAll with collection) use single HTTP requests for efficiency.

Error Conditions

Common Exceptions

// Invalid configuration
IllegalArgumentException

// Connection issues
java.net.http.HttpConnectTimeoutException

// Operation timeout
java.net.http.HttpTimeoutException

// Chroma server errors
RuntimeException (various, depends on error)

Error Scenarios

1. Dimension mismatch - all embeddings in a collection must have same dimensions
2. Invalid metadata - unsupported types (e.g., Boolean)
3. Connection failure - Chroma server not reachable
4. Timeout - operation exceeds configured timeout
5. Invalid filter - comparison operators on non-numeric values

Usage Guidelines

Best Practices

1. Reuse instances - create once, use many times
2. Use batch operations - addAll() for multiple embeddings
3. Configure timeouts - adjust based on operation size
4. Handle exceptions - network operations can fail
5. Validate dimensions - ensure all embeddings have same size

Anti-Patterns

1. Creating store per operation - expensive, creates new connections
2. Individual adds in loop - use addAll() instead
3. No error handling - network operations can fail
4. removeAll() without confirmation - destructive operation

Related APIs

• Builder - Configuration builder
• Search Types - Request and result types
• Core Types - Embedding, TextSegment, Metadata
• Filters - Metadata filtering

Examples

See:

• Add Operations
• Search Operations
• Remove Operations