CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

Overview
Eval results
Files

configuration.mddocs/guides/

Configuration Guide

Comprehensive guide to configuring ChromaEmbeddingStore.

Installation

Maven

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

Gradle

implementation 'dev.langchain4j:langchain4j-chroma:1.11.0'

Basic Configuration

Minimal Setup (V1)

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

Defaults:

  • API version: V1
  • Collection: "default"
  • Timeout: 5 seconds
  • Logging: disabled

Minimal Setup (V2)

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .build();

Defaults:

  • Tenant: "default"
  • Database: "default"
  • Collection: "default"
  • Timeout: 5 seconds

API Version Selection

V1 API (Default)

For Chroma 0.5.16+ with flat collection structure:

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V1)  // Optional, it's default
    .baseUrl("http://localhost:8000")
    .collectionName("my-documents")
    .build();

V2 API

For Chroma 0.7.0+ with hierarchical structure:

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

Configuration Parameters

baseUrl (Required)

// Local development
.baseUrl("http://localhost:8000")

// Remote server
.baseUrl("https://chroma.example.com")

// Custom port
.baseUrl("http://chroma-server:9000")

Required: Yes, no default

collectionName

.collectionName("documents")
.collectionName("user-embeddings")
.collectionName("knowledge-base")

Default: "default"

Naming:

  • Use descriptive names
  • Lowercase recommended
  • Hyphens or underscores for multi-word names

tenantName (V2 Only)

.tenantName("production")
.tenantName("customer-123")
.tenantName("team-alpha")

Default: "default"

Use cases:

  • Multi-tenancy isolation
  • Customer segregation
  • Environment separation

databaseName (V2 Only)

.databaseName("main")
.databaseName("analytics")
.databaseName("staging")

Default: "default"

Use cases:

  • Logical data separation
  • Application modules
  • Data lifecycle stages

timeout

import java.time.Duration;

// Short timeout for fast operations
.timeout(Duration.ofSeconds(5))   // Default

// Medium timeout
.timeout(Duration.ofSeconds(15))

// Long timeout for large batches
.timeout(Duration.ofSeconds(30))
.timeout(Duration.ofMinutes(1))

Default: 5 seconds

Guidelines:

  • Local server: 5-10 seconds
  • Remote server: 10-20 seconds
  • Large batches: 30-60 seconds

logRequests

.logRequests(true)   // Enable request logging
.logRequests(false)  // Disable (default)

Default: false

Use for:

  • Debugging API issues
  • Understanding request format
  • Development and testing

logResponses

.logResponses(true)   // Enable response logging
.logResponses(false)  // Disable (default)

Default: false

Use for:

  • Debugging response issues
  • Understanding response format
  • Development and testing

Environment-Specific Configurations

Development

ChromaEmbeddingStore devStore = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("dev-test")
    .timeout(Duration.ofSeconds(60))  // Generous timeout
    .logRequests(true)                // Debug info
    .logResponses(true)
    .build();

Staging

ChromaEmbeddingStore stagingStore = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("https://chroma-staging.example.com")
    .tenantName("staging")
    .databaseName("main")
    .collectionName("embeddings")
    .timeout(Duration.ofSeconds(20))
    .logRequests(false)
    .logResponses(false)
    .build();

Production

ChromaEmbeddingStore prodStore = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("https://chroma.example.com")
    .tenantName("production")
    .databaseName("primary")
    .collectionName("embeddings")
    .timeout(Duration.ofSeconds(15))
    .logRequests(false)               // Disable in prod
    .logResponses(false)
    .build();

Configuration from Properties

Using Spring Configuration

@Configuration
public class ChromaConfig {

    @Value("${chroma.base-url}")
    private String baseUrl;

    @Value("${chroma.collection-name}")
    private String collectionName;

    @Value("${chroma.timeout:10}")
    private int timeoutSeconds;

    @Bean
    public ChromaEmbeddingStore chromaEmbeddingStore() {
        return ChromaEmbeddingStore.builder()
            .baseUrl(baseUrl)
            .collectionName(collectionName)
            .timeout(Duration.ofSeconds(timeoutSeconds))
            .build();
    }
}

application.properties:

chroma.base-url=http://localhost:8000
chroma.collection-name=documents
chroma.timeout=15

Using Environment Variables

public class ChromaConfig {
    public static ChromaEmbeddingStore createStore() {
        String baseUrl = System.getenv().getOrDefault(
            "CHROMA_BASE_URL",
            "http://localhost:8000"
        );

        String collectionName = System.getenv().getOrDefault(
            "CHROMA_COLLECTION",
            "default"
        );

        int timeout = Integer.parseInt(
            System.getenv().getOrDefault("CHROMA_TIMEOUT", "10")
        );

        return ChromaEmbeddingStore.builder()
            .baseUrl(baseUrl)
            .collectionName(collectionName)
            .timeout(Duration.ofSeconds(timeout))
            .build();
    }
}

Multi-Store Configuration

Multiple Collections

// User documents
ChromaEmbeddingStore userDocs = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("user-documents")
    .build();

// System documentation
ChromaEmbeddingStore sysDocs = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("system-docs")
    .build();

Multi-Tenant Setup (V2)

// Tenant 1
ChromaEmbeddingStore tenant1 = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("customer-1")
    .databaseName("production")
    .collectionName("embeddings")
    .build();

// Tenant 2
ChromaEmbeddingStore tenant2 = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("customer-2")
    .databaseName("production")
    .collectionName("embeddings")
    .build();

Multiple Databases (V2)

// Production database
ChromaEmbeddingStore prod = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("my-tenant")
    .databaseName("production")
    .collectionName("embeddings")
    .build();

// Analytics database
ChromaEmbeddingStore analytics = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("my-tenant")
    .databaseName("analytics")
    .collectionName("embeddings")
    .build();

Advanced Configuration

Connection Pooling

ChromaEmbeddingStore reuses HTTP connections automatically. Create one instance and reuse it:

// GOOD - Create once, reuse many times
public class EmbeddingService {
    private final ChromaEmbeddingStore store;

    public EmbeddingService() {
        this.store = ChromaEmbeddingStore.builder()
            .baseUrl("http://localhost:8000")
            .build();
    }

    public void addDocument(Embedding emb, TextSegment seg) {
        store.add(emb, seg);
    }

    public EmbeddingSearchResult<TextSegment> search(Embedding query) {
        return store.search(
            EmbeddingSearchRequest.builder()
                .queryEmbedding(query)
                .maxResults(10)
                .build()
        );
    }
}

Factory Pattern

public class ChromaStoreFactory {

    public static ChromaEmbeddingStore createStore(String environment) {
        return switch (environment.toLowerCase()) {
            case "dev" -> ChromaEmbeddingStore.builder()
                .baseUrl("http://localhost:8000")
                .collectionName("dev")
                .timeout(Duration.ofSeconds(60))
                .logRequests(true)
                .build();

            case "staging" -> ChromaEmbeddingStore.builder()
                .baseUrl("https://chroma-staging.example.com")
                .collectionName("staging")
                .timeout(Duration.ofSeconds(20))
                .build();

            case "prod" -> ChromaEmbeddingStore.builder()
                .baseUrl("https://chroma.example.com")
                .collectionName("production")
                .timeout(Duration.ofSeconds(15))
                .build();

            default -> throw new IllegalArgumentException(
                "Unknown environment: " + environment
            );
        };
    }
}

Configuration Validation

Validation on Build

try {
    ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
        // .baseUrl(...) // Missing - will throw
        .build();
} catch (IllegalArgumentException e) {
    System.err.println("Configuration error: " + e.getMessage());
}

Testing Configuration

public class ChromaConfigTest {

    @Test
    public void testConnection() {
        ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
            .baseUrl("http://localhost:8000")
            .collectionName("test")
            .build();

        // Test with simple operation
        try {
            Embedding testEmb = Embedding.from(new float[]{1.0f, 0.0f, 0.0f});
            String id = store.add(testEmb);
            store.remove(id);
            System.out.println("Connection successful");
        } catch (Exception e) {
            System.err.println("Connection failed: " + e.getMessage());
        }
    }
}

Troubleshooting

Connection Refused

// Check baseUrl is correct
.baseUrl("http://localhost:8000")  // Not https, not missing port

// Ensure Chroma server is running:
// docker run -p 8000:8000 chromadb/chroma

Timeout Errors

// Increase timeout for slow operations
.timeout(Duration.ofSeconds(30))

// Or check network connectivity

Collection Not Found

Auto-creation should handle this. If issues persist:

  • Check Chroma server logs
  • Verify API version compatibility
  • Ensure Chroma server has write permissions

Best Practices

  1. Single instance per collection - Create once, reuse
  2. Use builders - Don't use deprecated constructors
  3. Externalize configuration - Use properties or env vars
  4. Set appropriate timeouts - Based on operation size
  5. Disable logging in production - For performance and security
  6. Use V2 for new projects - Better organization and features
  7. Test configuration early - Catch connection issues immediately

Related

  • Builder API - Complete API reference
  • ChromaApiVersion - Version selection
  • Migration Guide - Upgrading to V2

External Resources

  • Chroma Installation Guide
  • Docker Compose Setup

Install with Tessl CLI

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

docs

guides

batch-operations.md

configuration.md

error-handling.md

filtering.md

metadata.md

migration.md

performance.md

rag-pattern.md

semantic-search.md

index.md

tile.json