Chroma Android

⚠️ Chroma Android is currently in Beta

This means that the core APIs work well - but we are still gaining full confidence over all possible edge cases.

An Android library providing Chroma vector database functionality through a hybrid Rust/Java architecture.

What is Chroma?

Chroma is an open-source embedding database that helps developers build AI applications with memory capabilities. It enables easy vector search and storage of document embeddings, making it simple to create AI applications like "Chat your data" scenarios.

Quick Start

Installation

Note: For now, we're releasing this library as a pre-built .aar. If you need different architectures or need this to be published to a central repo, please file an issue.

• Check for the latest release in the releases.
• Pull down the .aar

Option 1 - Add to libs folder

• Create a folder ./app/libs in your Android project
• Place the chroma-android-release-0.0.1.aar file in this directory
• Update your settings.gradle (or settings.gradle.kts) file:
• Update your app build.gradle (or build.gradle.kts) file:
• Sync Gradle

settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        flatDir {
            dirs 'app/libs'
        }
    }
}

app/build.gradle:

dependencies {
    implementation(name: 'chroma-android-release-0.0.1', ext: 'aar')
}

Kotlin DSL (settings.gradle.kts):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        flatDir {
            dirs("app/libs")
        }
    }
}

Kotlin DSL (app/build.gradle.kts):

dependencies {
    implementation(name = "chroma-android-release-0.0.1", ext = "aar")
}

Option 2 - Java Module

In Android Studio:

• Choose File ▸ New ▸ New Module ▸ Import .JAR/.AAR Package
• Select your file: path/to/chroma-android-release-0.0.1.aar
• Creates a new module, e.g. :chroma-android
• Alter build.gradle with config below:
• Sync Gradle

Groovy:

dependencies {
    implementation project(":chroma-android")
}

Kotlin:

dependencies {
    implementation(project(":chroma-android"))
}

Client Types

ChromaDB Android provides two client types:

• EphemeralClient - Stores data in memory only. Perfect for testing, temporary workloads, or when persistence isn't needed. Data is lost when the client closes.
• PersistentClient - Stores data persistently to a directory. Data survives app restarts and is ideal for production use cases.

// In-memory storage (ephemeral)
try (EphemeralClient client = new EphemeralClient()) {
    // Data exists only during this try block
}

// Persistent storage 
try (PersistentClient client = new PersistentClient("/path/to/data")) {
    // Data persists across app sessions
    String storagePath = client.getPersistPath(); // Get storage location
}

Basic Usage

import com.trychroma.android.EphemeralClient;
import com.trychroma.android.PersistentClient;
import com.trychroma.android.Collection;
import com.trychroma.android.Document;
import com.trychroma.android.DocumentResult;
import com.trychroma.android.Query;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Initialize ChromaDB client (in-memory)
try (EphemeralClient client = new EphemeralClient()) {
    // Or create persistent client:
    // try (PersistentClient client = new PersistentClient("/path/to/chroma/data")) {

    // Create a collection
    Collection collection = client.createCollection("my_documents");

    // Add documents with embeddings and metadata
    Map<String, Object> metadata = new HashMap<>();
    metadata.put("category", "science");
    metadata.put("year", 2025);
    
    List<Document> docs = Arrays.asList(
        new Document("doc1", new float[]{0.1f, 0.2f, 0.3f}, "Scientific paper about AI", metadata, "https://example.com/doc1"),
        new Document("doc2", new float[]{0.4f, 0.5f, 0.6f}, "Research on neural networks")
    );
    collection.add(docs);

    // Simple query - find 2 most similar documents
    List<DocumentResult> results = collection.query(
        new float[][]{{0.1f, 0.2f, 0.3f}}, 
        2
    );
    
    // Advanced query using Query object
    Query advancedQuery = new Query.Builder()
        .queryEmbeddings(new float[][]{{0.1f, 0.2f, 0.3f}})
        .nResults(5)
        .where("""
            {"category": "science"}
            """)
        .build();
    
    List<DocumentResult> advancedResults = collection.query(advancedQuery);
    
    // Process results - each DocumentResult contains document data and distance
    for (DocumentResult result : advancedResults) {
        Document doc = result;
        System.out.println("Found: " + doc.getId() + 
                          " (distance: " + result.getDistance() + 
                          ", category: " + doc.getMetadata().get("category") + ")");
    }
    // Client auto-closes with try-with-resources
}

Querying Collections with Query.Builder

The Query class provides a flexible approach for complex queries:

Query query = new Query.Builder()
    .queryEmbeddings(embeddings)
    .nResults(10)
    .where("""
        {"year": {"$gt": 2020}}
        """)         // Metadata filtering
    .ids(new String[]{"doc1", "doc2", "doc5"})    // Search specific documents
    .build();

List<DocumentResult> results = collection.query(query);

Metadata Filtering

ChromaDB supports rich metadata queries using JSON filter syntax:

// Exact match
.where("""
    {"category": "science"}
    """)

// Comparison operators
.where("""
    {"year": {"$gt": 2020, "$lte": 2023}}
    """)

// Multiple conditions
.where("""
    {"category": "science", "published": true}
    """)

// Different data types
.where("""
    {"year": 2023}
    """)        // Integer

.where("""
    {"active": true}
    """)       // Boolean

.where("""
    {"category": "technology"}
    """)       // String

Advanced Query Features

The Android library now supports all major ChromaDB query features:

// Combine multiple filters
Query comprehensiveQuery = new Query.Builder()
    .queryEmbeddings(new float[][]{{0.1f, 0.2f, 0.3f}})
    .nResults(5)
    .where("{\"category\": \"science\", \"year\": 2023}")  // Metadata filtering
    .ids(new String[]{"doc1", "doc3", "doc5"})             // ID filtering  
    .build();

List<DocumentResult> results = collection.query(comprehensiveQuery);

Working with Results

The query API returns results as a list of DocumentResult objects:

Note: A DocumentResult is a Document that has result specific metadata (like getDistance())

List<DocumentResult> results = collection.query(query);

System.out.println("Query results (" + results.size() + " found):");

for (DocumentResult result : results) {
    System.out.println("  📄 " + result.getId() + " (distance: " + result.getDistance() + ")");
    System.out.println("     Content: " + result.getData());
    
    if (result.getMetadata() != null) {
        System.out.println("     Metadata: " + result.getMetadata());
    }
    
    if (result.getUri() != null) {
        System.out.println("     Source: " + result.getUri());
    }
}

Requirements

• Android: API level 21 (Android 5.0) or higher
• NDK: Version 26.3.11579264 (for building from source)

Development

For development setup and building from source, see DEVELOP.md.

License

Apache 2.0 - See LICENSE for details.

Links

• Chroma Core - The main Chroma project
• Documentation - Official Chroma documentation