ChromaEmbeddingStore.Builder API

Builder class for constructing ChromaEmbeddingStore instances with flexible configuration.

package dev.langchain4j.store.embedding.chroma;

public static class Builder

Methods

apiVersion

public Builder apiVersion(ChromaApiVersion apiVersion);

Sets the Chroma API version (V1 or V2).

Parameters:

• apiVersion - API version enum value

Default: ChromaApiVersion.V1

Example:

.apiVersion(ChromaApiVersion.V2)

See: ChromaApiVersion

baseUrl

public Builder baseUrl(String baseUrl);

Sets the base URL of the Chroma service.

Parameters:

• baseUrl - URL including protocol and port

Required: Yes

Example:

.baseUrl("http://localhost:8000")
.baseUrl("https://chroma.example.com")

tenantName

public Builder tenantName(String tenantName);

Sets the tenant name for V2 API.

Parameters:

• tenantName - tenant identifier

Default: "default"

API Version: V2 only (ignored in V1)

Example:

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

databaseName

public Builder databaseName(String databaseName);

Sets the database name for V2 API.

Parameters:

• databaseName - database identifier

Default: "default"

API Version: V2 only (ignored in V1)

Example:

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

collectionName

public Builder collectionName(String collectionName);

Sets the collection name.

Parameters:

• collectionName - collection identifier

Default: "default"

Example:

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

timeout

public Builder timeout(java.time.Duration timeout);

Sets timeout duration for HTTP requests.

Parameters:

• timeout - timeout duration

Default: Duration.ofSeconds(5)

Example:

.timeout(Duration.ofSeconds(10))
.timeout(Duration.ofMinutes(1))

logRequests

public Builder logRequests(boolean logRequests);

Enables or disables request logging.

Parameters:

• logRequests - true to enable logging

Default: false

Example:

.logRequests(true)

logResponses

public Builder logResponses(boolean logResponses);

Enables or disables response logging.

Parameters:

• logResponses - true to enable logging

Default: false

Example:

.logResponses(true)

build

public ChromaEmbeddingStore build();

Builds the ChromaEmbeddingStore instance.

Returns: configured store instance

Throws: IllegalArgumentException if configuration is invalid

Example:

ChromaEmbeddingStore store = builder.build();

Configuration Examples

Minimal V1 Configuration

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

Uses defaults:

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

Full V1 Configuration

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

Minimal V2 Configuration

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

Uses defaults:

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

Full V2 Configuration

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("http://localhost:8000")
    .tenantName("production")
    .databaseName("main")
    .collectionName("documents")
    .timeout(Duration.ofSeconds(30))
    .logRequests(true)
    .logResponses(true)
    .build();

Production Configuration

ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
    .apiVersion(ChromaApiVersion.V2)
    .baseUrl("https://chroma.production.com")
    .tenantName("prod-tenant")
    .databaseName("primary")
    .collectionName("embeddings")
    .timeout(Duration.ofSeconds(20))
    .logRequests(false)
    .logResponses(false)
    .build();

Development Configuration

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

Configuration Notes

Required vs Optional

Required:

• baseUrl - must be set

Optional (with defaults):

• apiVersion - defaults to V1
• collectionName - defaults to "default"
• tenantName - defaults to "default" (V2 only)
• databaseName - defaults to "default" (V2 only)
• timeout - defaults to 5 seconds
• logRequests - defaults to false
• logResponses - defaults to false

V1 vs V2 Configuration

V1 API:

• tenantName and databaseName are ignored
• Flat structure: only collection name matters
• Compatible with Chroma 0.5.16+

V2 API:

• Hierarchical: tenant → database → collection
• tenantName and databaseName are used
• Auto-creates tenant and database if they don't exist
• Compatible with Chroma 0.7.0+

Auto-Creation Behavior

When store is instantiated:

V1:

• Collection is created if it doesn't exist

V2:

• Tenant is created if it doesn't exist
• Database is created if it doesn't exist
• Collection is created if it doesn't exist

Timeout Guidelines

Choose timeout based on operation size:

// Small operations, local network
.timeout(Duration.ofSeconds(5))   // Default

// Medium operations, remote network
.timeout(Duration.ofSeconds(15))

// Large batch operations
.timeout(Duration.ofSeconds(30))

// Very large operations or slow network
.timeout(Duration.ofSeconds(60))

Logging Guidelines

Enable logging when:

• Debugging connection issues
• Troubleshooting API errors
• Development and testing
• Understanding request/response format

Disable logging when:

• Production environments
• Performance is critical
• Handling sensitive data

// Development
.logRequests(true)
.logResponses(true)

// Production
.logRequests(false)
.logResponses(false)

Validation

Builder validates configuration on build():

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

Common validation errors:

• Missing baseUrl
• Invalid URL format
• Negative timeout duration
• Null parameter values

Builder Pattern Benefits

1. Readable configuration - clear parameter names
2. Optional parameters - only set what you need
3. Validation - catches errors early
4. Flexibility - easy to add new parameters
5. Immutability - store is immutable after creation

Related APIs

• ChromaEmbeddingStore - Main store class
• ChromaApiVersion - API version enum
• Configuration Guide - Detailed configuration guide

Examples

See: Configuration Guide for more examples and patterns.