tessl/maven-dev-langchain4j--langchain4j-chroma

LangChain4j integration for Chroma embedding store enabling storage, retrieval, and similarity search of vector embeddings with metadata filtering support for both API V1 and V2.

—

Pending

Overview

Eval results

Files

LangChain4j Chroma Embedding Store

Name: tessl/maven-dev-langchain4j--langchain4j-chroma
Author: tessl

Java integration for Chroma vector database providing storage, retrieval, and similarity search of embeddings. Implements LangChain4j's EmbeddingStore interface with metadata filtering support for both Chroma API V1 (0.5.16+) and V2 (0.7.0+).

Quick Start

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-chroma</artifactId>
    <version>1.11.0</version>
</dependency>

Minimal setup:

import dev.langchain4j.store.embedding.chroma.ChromaEmbeddingStore;
import dev.langchain4j.data.embedding.Embedding;

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

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

// Search
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(10)
    .build();
EmbeddingSearchResult<TextSegment> results = store.search(request);

Core Imports

// Main classes
import dev.langchain4j.store.embedding.chroma.ChromaEmbeddingStore;
import dev.langchain4j.store.embedding.chroma.ChromaApiVersion;

// Core types (langchain4j-core)
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.data.document.Metadata;
import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingSearchResult;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.filter.Filter;

Essential Concepts

Distance Metric: Always uses cosine distance (hnsw:space = cosine)

Score Calculation: score = 1 - (distance / 2) where distance ∈ [0, 2]

Score range: [0, 1] where 1 is perfect match

Auto-creation: Collections are automatically created if they don't exist

API Versions:

V1 (default): Flat structure, Chroma 0.5.16+
V2: Hierarchical tenant/database/collection, Chroma 0.7.0+

Common Operations

Add Embeddings

// Single with auto-generated ID
String id = store.add(embedding);

// Single with specific ID
store.add("custom-id", embedding);

// With text segment and metadata
TextSegment segment = TextSegment.from(
    "document text",
    new Metadata().put("author", "John").put("year", 2024)
);
String id = store.add(embedding, segment);

// Batch add (efficient)
List<String> ids = store.addAll(embeddings);

See: Add Operations | Metadata Guide

Search for Similar Embeddings

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

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

for (EmbeddingMatch<TextSegment> match : result.matches()) {
    double score = match.score();
    String id = match.embeddingId();
    TextSegment segment = match.embedded();
}

See: Search Operations | Filtering Guide

Search with Metadata Filters

import static dev.langchain4j.store.embedding.filter.MetadataFilterBuilder.*;

Filter filter = metadataKey("author").isEqualTo("John Doe")
    .and(metadataKey("year").isGreaterThanOrEqualTo(2020));

EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(5)
    .filter(filter)
    .build();

See: Filtering Guide | Filter API

Remove Embeddings

// Single ID
store.remove("id-to-remove");

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

// By metadata filter
store.removeAll(metadataKey("status").isEqualTo("outdated"));

// All embeddings
store.removeAll();

See: Remove Operations

Configuration

V1 API (Default)

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("my-documents")
    .timeout(Duration.ofSeconds(10))
    .logRequests(true)
    .logResponses(true)
    .build();

V2 API (Hierarchical)

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("my-tenant")      // Default: "default"
    .databaseName("my-database")   // Default: "default"
    .collectionName("my-documents")
    .timeout(Duration.ofSeconds(10))
    .build();

See: Configuration Guide | Builder API

Integration Patterns

RAG Pattern - Retrieval-Augmented Generation
Semantic Search - Search with metadata
Batch Operations - Performance optimization
Error Handling - Exception management

API Reference

ChromaEmbeddingStore - Main store class
Builder - Configuration builder
ChromaApiVersion - API version enum
Core Types - Embedding, TextSegment, Metadata
Search Types - Request and result objects
Filters - Metadata filtering

Performance Tips

Use batch operations for multiple embeddings:

// Good: Single HTTP request
List<String> ids = store.addAll(embeddings);

// Bad: N HTTP requests
for (Embedding e : embeddings) { store.add(e); }

Reuse store instances - don't create per operation

Adjust timeouts for large operations:

.timeout(Duration.ofSeconds(30))

See: Performance Guide

Migration

Migrating from V1 to V2:

// V1 → V2: Add apiVersion and optional tenant/database
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)  // Add this
    .baseUrl("http://localhost:8000")
    .tenantName("my-tenant")          // Optional
    .databaseName("my-database")       // Optional
    .collectionName("my-collection")
    .build();

See: Migration Guide

Troubleshooting

Common issues:

Connection refused: Ensure Chroma server is running on baseUrl
Timeout errors: Increase timeout for large operations
Filter errors: Comparison operators (>, <) only work with numeric values
Dimension mismatch: All embeddings in a collection must have same dimensions

See: Error Handling Guide

External Resources

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-chroma