ChromaDB Dart Client

Discord

Dart client for ChromaDB with collections, vector search, multi-tenant storage, embeddings, and RAG pipelines. It gives Dart and Flutter applications a pure Dart, type-safe client across iOS, Android, macOS, Windows, Linux, Web, and server-side Dart.

Tip

Coding agents: start with llms.txt. It links to the package docs, examples, and optional references in a compact format.

Table of Contents

Features
Why choose this client?
Quickstart
Configuration
Usage
Error Handling
Examples
API Coverage
Official Documentation
Sponsor
License

Features

Collection and record management

Create, list, update, fork, and delete collections
Add, update, upsert, get, count, and delete records
Attach documents, embeddings, metadata, and record filters

Search and operational tooling

Similarity queries with where and whereDocument filtering
High-level ChromaCollection wrapper with auto-embedding
Embedding functions, tenant, database, auth, and health resources for managed deployments

Why choose this client?

Pure Dart with no Flutter dependency — works in mobile apps, backends, and CLIs.
Type-safe request and response models with minimal dependencies (http, logging, meta).
Retries, interceptors, and error handling built into the client.
Includes both low-level resources and a high-level ChromaCollection wrapper for auto-embedding workflows.

Quickstart

dependencies:
  chromadb: ^1.1.1

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.getOrCreateCollection(name: 'my-documents');

    await collection.add(
      ids: ['doc-1'],
      embeddings: [
        [0.1, 0.2, 0.3],
      ],
      documents: ['Hello from ChromaDB'],
    );

    final results = await collection.query(
      queryEmbeddings: [
        [0.1, 0.2, 0.3],
      ],
      nResults: 1,
    );

    print(results.ids);
  } finally {
    client.close();
  }
}

Configuration

Configure hosts, tenants, databases, and auth

Use the default constructor for local development, or pass a ChromaConfig when you need Chroma Cloud credentials, custom tenants, or non-default databases.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient(
    config: ChromaConfig(
      baseUrl: 'http://localhost:8000',
      tenant: 'default_tenant',
      database: 'default_database',
      retryPolicy: RetryPolicy(
        maxRetries: 3,
        initialDelay: Duration(seconds: 1),
      ),
    ),
  );

  client.close();
}

Use ApiKeyProvider or BasicAuthProvider for secured or hosted deployments.

Usage

How do I manage collections?

Show example

Collections are the main organizational unit in ChromaDB. The client provides direct helpers for create, get, list, count, and delete operations without dropping down to raw HTTP calls.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.createCollection(
      name: 'my-docs',
      metadata: {'source': 'docs'},
    );

    print(collection.name);
  } finally {
    client.close();
  }
}

→ Full example

How do I add records?

Show example

Use add, update, or upsert depending on whether you want strict inserts or idempotent writes. Typed parameters make it clear which vectors, documents, and metadata travel together.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.getOrCreateCollection(name: 'docs');

    await collection.add(
      ids: ['id-1', 'id-2'],
      embeddings: [
        [1.0, 2.0, 3.0],
        [4.0, 5.0, 6.0],
      ],
      documents: ['Doc 1', 'Doc 2'],
      metadatas: [
        {'source': 'web'},
        {'source': 'pdf'},
      ],
    );
  } finally {
    client.close();
  }
}

→ Full example

How do I auto-embed data?

Show example

The high-level ChromaCollection wrapper can call an embedding function automatically, which removes a manual vectorization step from your Dart RAG pipeline.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.getOrCreateCollection(
      name: 'auto-embedded',
      embeddingFunction: MyEmbeddingFunction(),
    );

    await collection.add(
      ids: ['doc-1'],
      documents: ['Dart works well for CLIs and servers.'],
    );
  } finally {
    client.close();
  }
}

class MyEmbeddingFunction implements EmbeddingFunction {
  @override
  Future<List<List<double>>> generate(List<Embeddable> inputs) async {
    return List.generate(inputs.length, (_) => [0.1, 0.2, 0.3]);
  }
}

→ Full example

How do I query similar records?

Show example

Queries accept vector inputs, result counts, and include flags, which makes semantic search straightforward from Dart. This is the main building block for retrieval and RAG layers.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.getOrCreateCollection(name: 'docs');
    final results = await collection.query(
      queryEmbeddings: [
        [0.1, 0.2, 0.3],
      ],
      nResults: 3,
    );

    print(results.ids);
  } finally {
    client.close();
  }
}

→ Full example

How do I filter by metadata?

Show example

Metadata filtering is part of the search request, which keeps retrieval logic on the server side instead of post-processing in the app. This is useful for tenant scoping, document classes, and content freshness filters.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final collection = await client.getOrCreateCollection(name: 'docs');
    final results = await collection.query(
      queryEmbeddings: [
        [0.1, 0.2, 0.3],
      ],
      nResults: 5,
      where: {'source': 'web'},
    );

    print(results.ids);
  } finally {
    client.close();
  }
}

→ Full example

How do I work with tenants and databases?

Show example

Multi-tenant operations are exposed directly on the client, which is useful for SaaS control planes and managed ChromaDB installations. You do not need separate admin bindings for these workflows.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final tenant = await client.tenants.getByName(name: 'default_tenant');
    print(tenant.name);
  } finally {
    client.close();
  }
}

→ Full example

How do I check server health?

Show example

Health endpoints are useful for deployment checks and CI smoke tests. Keeping them in the same client helps when you bundle ChromaDB into local tooling or managed dashboards.

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    final heartbeat = await client.health.heartbeat();
    print(heartbeat.nanosecondHeartbeat);
  } finally {
    client.close();
  }
}

→ Full example

Error Handling

Handle API failures, validation issues, and connection problems

chromadb throws typed exceptions so retrieval code can distinguish between auth errors, server errors, validation problems, and timeouts. Catch ApiException first for HTTP failures, then fall back to ChromaException for other client-side errors.

import 'dart:io';

import 'package:chromadb/chromadb.dart';

Future<void> main() async {
  final client = ChromaClient();

  try {
    await client.health.version();
  } on ApiException catch (error) {
    stderr.writeln('ChromaDB API error ${error.statusCode}: ${error.message}');
  } on ChromaException catch (error) {
    stderr.writeln('ChromaDB client error: $error');
  } finally {
    client.close();
  }
}

→ Full example

Examples

See the example/ directory for complete examples:

Example	Description
`collections_example.dart`	Collection management
`records_example.dart`	Record operations
`query_example.dart`	Similarity queries
`metadata_filtering_example.dart`	Metadata filtering
`embedding_function_example.dart`	Auto-embedding workflows
`functions_example.dart`	Embedding functions
`multi_tenant_example.dart`	Multi-tenant deployments
`databases_example.dart`	Database management
`auth_example.dart`	Authentication
`health_example.dart`	Server health checks
`error_handling_example.dart`	Exception handling patterns
`chromadb_example.dart`	Quick-start overview
`tenants_example.dart`	Tenant management

API Coverage

API	Status
Collections	✅ Full
Records	✅ Full
Functions	✅ Full
Databases	✅ Full
Tenants	✅ Full
Auth	✅ Full
Health	✅ Full

Official Documentation

If these packages are useful to you or your company, please consider sponsoring the project. Development and maintenance are provided to the community for free, but integration tests against real APIs and the tooling required to build and verify releases still have real costs. Your support, at any level, helps keep these packages maintained and free for the Dart & Flutter community.

License

This package is licensed under the MIT License.

This is a community-maintained package and is not affiliated with or endorsed by Chroma.

ChromaDB Dart Client

Features

Collection and record management

Search and operational tooling

Why choose this client?

Quickstart

Configuration

Usage

How do I manage collections?

How do I add records?

How do I auto-embed data?

How do I query similar records?

How do I filter by metadata?

How do I work with tenants and databases?

How do I check server health?

Error Handling

Examples

API Coverage

Official Documentation

License

Libraries

chromadb package

ChromaDB Dart Client

Features

Collection and record management

Search and operational tooling

Why choose this client?

Quickstart

Configuration

Usage

How do I manage collections?

How do I add records?

How do I auto-embed data?

How do I query similar records?

How do I filter by metadata?

How do I work with tenants and databases?

How do I check server health?

Error Handling

Examples

API Coverage

Official Documentation

Sponsor

License

Libraries

chromadb package