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

Search Operations

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

Finding similar embeddings in the Chroma vector store using cosine similarity.

Basic Search

Simple Search

import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingSearchResult;
import dev.langchain4j.data.embedding.Embedding;

Embedding queryEmbedding = Embedding.from(new float[]{0.15f, 0.25f, 0.35f});

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

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

With Minimum Score Threshold

EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(10)
    .minScore(0.7)  // Only return matches with score >= 0.7
    .build();

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

Processing Results

Extracting Match Information

import dev.langchain4j.store.embedding.EmbeddingMatch;

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

for (EmbeddingMatch<TextSegment> match : result.matches()) {
    // Similarity score (0.0 to 1.0, higher is more similar)
    double score = match.score();

    // Embedding ID
    String embeddingId = match.embeddingId();

    // The matching embedding vector
    Embedding matchedEmbedding = match.embedding();

    // Associated text segment (may be null)
    TextSegment textSegment = match.embedded();
}

Accessing Text and Metadata

for (EmbeddingMatch<TextSegment> match : result.matches()) {
    TextSegment segment = match.embedded();

    if (segment != null) {
        // Get text content
        String text = segment.text();

        // Get metadata
        Metadata metadata = segment.metadata();
        if (metadata != null) {
            String author = metadata.getString("author");
            Integer year = metadata.getInteger("year");
        }
    }
}

Stream Processing

import java.util.stream.Collectors;

List<String> relevantTexts = result.matches().stream()
    .filter(match -> match.score() > 0.8)
    .map(match -> match.embedded().text())
    .collect(Collectors.toList());

Search with Filters

Single Condition Filter

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

Filter filter = metadataKey("author").isEqualTo("John Doe");

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

Numeric Comparison Filters

// Greater than or equal
Filter yearFilter = metadataKey("year").isGreaterThanOrEqualTo(2020);

// Greater than
Filter scoreFilter = metadataKey("score").isGreaterThan(7.5);

// Less than or equal
Filter priceFilter = metadataKey("price").isLessThanOrEqualTo(100.0);

// Less than
Filter ageFilter = metadataKey("age").isLessThan(30);

Important: Comparison operators only work with numeric metadata values in Chroma.

Multiple Values (IN/NOT IN)

// Match any of the values
Filter categoryFilter = metadataKey("category")
    .isIn(Arrays.asList("tech", "science", "math"));

// Exclude values
Filter excludeFilter = metadataKey("status")
    .isNotIn(Arrays.asList("draft", "archived"));

Combining Filters with AND

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

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

Combining Filters with OR

Filter orFilter = metadataKey("category").isEqualTo("tech")
    .or(metadataKey("category").isEqualTo("science"))
    .or(metadataKey("category").isEqualTo("math"));

Complex Nested Filters

// (status = "published") AND ((priority >= 5) OR (urgent = true))
Filter complex = metadataKey("status").isEqualTo("published")
    .and(
        metadataKey("priority").isGreaterThanOrEqualTo(5)
        .or(metadataKey("urgent").isEqualTo(true))
    );

NOT Filters

// Exclude specific value
Filter notArchived = metadataKey("status").isNotEqualTo("archived");

// Alternative using NOT wrapper (automatically converted)
Filter notDraft = Filter.not(metadataKey("status").isEqualTo("draft"));

Note: Chroma doesn't natively support NOT operations. The library converts them to equivalent positive operations where possible.

Score Interpretation

Score Calculation

// Chroma uses cosine distance
// distance range: [0, 2]
// score = 1 - (distance / 2)
// score range: [0, 1]

// Examples:
// distance = 0.0  → score = 1.0 (perfect match)
// distance = 1.0  → score = 0.5 (orthogonal)
// distance = 2.0  → score = 0.0 (opposite)

Score Thresholds

Common threshold guidelines:

// Very strict - only near-perfect matches
.minScore(0.95)

// Strict - very similar content
.minScore(0.85)

// Moderate - reasonably similar
.minScore(0.70)

// Loose - any similarity
.minScore(0.50)

// Very loose - include marginally related
.minScore(0.30)

Common Search Patterns

Semantic Search

import dev.langchain4j.model.embedding.EmbeddingModel;

String userQuery = "What is machine learning?";

// Convert query to embedding
EmbeddingModel model = createEmbeddingModel();
Embedding queryEmbedding = model.embed(userQuery).content();

// Search for similar content
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(5)
    .minScore(0.7)
    .build();

List<String> relevantDocs = store.search(request).matches().stream()
    .map(match -> match.embedded().text())
    .collect(Collectors.toList());

RAG Context Retrieval

// Retrieve context for RAG (Retrieval-Augmented Generation)
String question = "How does authentication work?";
Embedding queryEmbedding = model.embed(question).content();

EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(3)
    .minScore(0.75)
    .build();

String context = store.search(request).matches().stream()
    .map(match -> match.embedded().text())
    .collect(Collectors.joining("\n\n"));

// Use context with LLM
String prompt = "Context:\n" + context + "\n\nQuestion: " + question;

Filtered Semantic Search

String query = "recent AI advances";
Embedding queryEmbedding = model.embed(query).content();

// Only search in recent, published documents
Filter filter = metadataKey("status").isEqualTo("published")
    .and(metadataKey("year").isGreaterThanOrEqualTo(2023))
    .and(metadataKey("category").isEqualTo("AI"));

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

Finding Near Duplicates

// Find near-duplicate content
Embedding documentEmbedding = getDocumentEmbedding();

EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(documentEmbedding)
    .maxResults(10)
    .minScore(0.95)  // Very high threshold for near-duplicates
    .build();

// Filter out the document itself if needed
List<EmbeddingMatch<TextSegment>> duplicates =
    store.search(request).matches().stream()
        .filter(match -> !match.embeddingId().equals(originalDocId))
        .collect(Collectors.toList());

Category-Based Search

// Search within specific categories
List<String> allowedCategories = Arrays.asList("tech", "science", "engineering");

Filter categoryFilter = metadataKey("category").isIn(allowedCategories);

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

Time-Bounded Search

// Search only recent documents (last 90 days)
long ninetyDaysAgo = System.currentTimeMillis() - (90L * 24 * 60 * 60 * 1000);

Filter timeFilter = metadataKey("timestamp").isGreaterThanOrEqualTo(ninetyDaysAgo);

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

Performance Considerations

Result Limits

// Smaller maxResults = faster search
.maxResults(5)   // Fast, good for most use cases
.maxResults(50)  // Moderate, for broader exploration
.maxResults(100) // Slower, for comprehensive results

Using Minimum Score

// minScore acts as early termination hint
// Can improve performance by reducing result processing
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(100)
    .minScore(0.8)  // May return fewer than 100 results
    .build();

Filter Selectivity

More selective filters improve performance:

// Less selective - scans more data
Filter broad = metadataKey("year").isGreaterThan(2000);

// More selective - scans less data
Filter specific = metadataKey("status").isEqualTo("published")
    .and(metadataKey("year").isEqualTo(2024))
    .and(metadataKey("category").isEqualTo("AI"));

Error Handling

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

} catch (IllegalArgumentException e) {
    // Invalid request parameters
    System.err.println("Invalid search request: " + e.getMessage());

} catch (java.net.http.HttpTimeoutException e) {
    // Search timed out
    System.err.println("Search timed out: " + e.getMessage());

} catch (Exception e) {
    // Other errors (network, Chroma errors)
    System.err.println("Search failed: " + e.getMessage());
}

Limitations

Filter Limitations:

Comparison operators (>, >=, <, <=) only work with numeric values
String comparisons using operators are not supported
NOT operations are converted to equivalent positive operations

Embedding Limitations:

Query embedding must have same dimensions as stored embeddings
Distance metric is always cosine (cannot be changed)

API Reference

See: EmbeddingSearchRequest API for complete type signatures.

Related:

Install with Tessl CLI

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