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.
version.mddocs/api/
ChromaApiVersion API
Enum for specifying Chroma REST API version.
package dev.langchain4j.store.embedding.chroma;
public enum ChromaApiVersionValues
V1
V1Chroma API V1 - compatible with Chroma 0.5.16+.
Characteristics:
- Flat collection structure
- No tenant/database hierarchy
- Simpler configuration
- Stable and widely supported
Usage:
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V1)
.baseUrl("http://localhost:8000")
.collectionName("my-collection")
.build();V2
V2Chroma API V2 - compatible with Chroma 0.7.0+ (1.1.0).
Characteristics:
- Hierarchical tenant/database/collection structure
- Multi-tenancy support
- Database isolation
- Auto-creates tenant and database
Usage:
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.tenantName("my-tenant")
.databaseName("my-database")
.collectionName("my-collection")
.build();Comparison
| Feature | V1 | V2 |
|---|---|---|
| Chroma Version | 0.5.16+ | 0.7.0+ (1.1.0) |
| Structure | Flat | Hierarchical |
| Tenant Support | No | Yes |
| Database Support | No | Yes |
| Default Tenant | N/A | "default" |
| Default Database | N/A | "default" |
| Auto-creation | Collection | Tenant, DB, Collection |
| Configuration | Simple | More options |
Choosing a Version
Use V1 When:
- Using Chroma 0.5.x or 0.6.x
- Simple single-collection use case
- Don't need multi-tenancy
- Want minimal configuration
- Existing code uses V1
Use V2 When:
- Using Chroma 0.7.0+ (1.1.0)
- Need multi-tenancy support
- Want database isolation
- Organizing collections hierarchically
- Building new applications
Default Behavior
If not specified, ChromaEmbeddingStore defaults to V1:
// Defaults to V1
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.baseUrl("http://localhost:8000")
.collectionName("my-collection")
.build();
// Equivalent to
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V1) // Default
.baseUrl("http://localhost:8000")
.collectionName("my-collection")
.build();Configuration Examples
V1 Configuration
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V1)
.baseUrl("http://localhost:8000")
.collectionName("documents")
.build();Configuration used:
- API: V1
- Collection: "documents"
Ignored parameters:
tenantName- not used in V1databaseName- not used in V1
V2 Minimal Configuration
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.collectionName("documents")
.build();Configuration used:
- API: V2
- Tenant: "default" (default)
- Database: "default" (default)
- Collection: "documents"
V2 Full Configuration
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.tenantName("production")
.databaseName("main")
.collectionName("documents")
.build();Configuration used:
- API: V2
- Tenant: "production"
- Database: "main"
- Collection: "documents"
Multi-Tenancy with V2
V2 enables organizing collections by tenant and database:
// Tenant 1, Database A
ChromaEmbeddingStore store1 = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.tenantName("customer-1")
.databaseName("production")
.collectionName("embeddings")
.build();
// Tenant 1, Database B
ChromaEmbeddingStore store2 = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.tenantName("customer-1")
.databaseName("staging")
.collectionName("embeddings")
.build();
// Tenant 2, Database A
ChromaEmbeddingStore store3 = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2)
.baseUrl("http://localhost:8000")
.tenantName("customer-2")
.databaseName("production")
.collectionName("embeddings")
.build();These are completely isolated from each other.
Migration from V1 to V2
Before (V1)
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.baseUrl("http://localhost:8000")
.collectionName("my-collection")
.build();After (V2)
ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
.apiVersion(ChromaApiVersion.V2) // Add this
.baseUrl("http://localhost:8000")
.tenantName("default") // Optional, defaults to "default"
.databaseName("default") // Optional, defaults to "default"
.collectionName("my-collection")
.build();See: Migration Guide for detailed migration instructions.
Version Detection
ChromaEmbeddingStore uses the configured API version for all operations. There is no automatic version detection or fallback.
Important: Ensure your Chroma server version matches the API version:
// Chroma 0.5.x/0.6.x → Use V1
.apiVersion(ChromaApiVersion.V1)
// Chroma 0.7.0+ (1.1.0) → Use V2
.apiVersion(ChromaApiVersion.V2)API Stability
V1
- Stable and mature
- Wide compatibility (Chroma 0.5.16+)
- No breaking changes expected
V2
- Newer API
- Compatible with Chroma 0.7.0+ (1.1.0)
- Recommended for new projects
Related APIs
- Builder - Configuration builder with apiVersion
- Configuration Guide - Detailed setup examples
- Migration Guide - V1 to V2 migration
External Documentation
Install with Tessl CLI
npx tessl i tessl/maven-dev-langchain4j--langchain4j-chroma@1.11.0