ChromaDB.Client

ChromaDB.Client, published on NuGet as ChromaDotNet.Client, is a .NET client for Chroma and Chroma Cloud. It covers:

• collections, tenants and databases;
• writing and reading records, and nearest neighbor queries with filters;
• the Search API of Chroma Cloud, with hybrid BM25 search;
• OpenTelemetry traces and metrics.

This is a community project, the continuation of ssone95/ChromaDB.Client, kept up to date with current Chroma versions. It is not affiliated with or endorsed by Chroma. See About this fork.

Website: chromadotnet.org

Used by

• CommunityToolkit.VectorData.Chroma, the Chroma provider for Microsoft.Extensions.VectorData in the AI Community Toolkit of the .NET Foundation. It works with Semantic Kernel and Agent Framework.

Installation

dotnet add package ChromaDotNet.Client

ChromaDotNet.Client.DependencyInjection for Microsoft.Extensions.DependencyInjection: Dependency injection.

Example

The models, like ChromaRecords, ChromaQuery and ChromaCollectionDefinition, are in ChromaDB.Client.Models. AddChromaClient is in ChromaDB.Client.DependencyInjection.

using ChromaDB.Client;
using ChromaDB.Client.Models;

var configOptions = new ChromaConfigurationOptions(uri: "http://localhost:8000/api/v2/");
using var httpClient = new HttpClient();
var client = new ChromaClient(configOptions, httpClient);

Console.WriteLine(await client.GetVersionAsync());

var string5Collection = await client.GetOrCreateCollectionAsync("string5");
var string5Client = new ChromaCollectionClient(string5Collection, configOptions, httpClient);

await string5Client.AddAsync(["340a36ad-c38a-406c-be38-250174aee5a4"], embeddings: [new([1f, 0.5f, 0f, -0.5f, -1f])]);

var getResult = await string5Client.GetAsync("340a36ad-c38a-406c-be38-250174aee5a4", include: ChromaGetInclude.Metadatas | ChromaGetInclude.Documents | ChromaGetInclude.Embeddings);
Console.WriteLine($"ID: {getResult!.Id}");

var queryData = await string5Client.QueryAsync([new([1f, 0.5f, 0f, -0.5f, -1f]), new([1.5f, 0f, 2f, -1f, -1.5f])], include: ChromaQueryInclude.Metadatas | ChromaQueryInclude.Distances);
foreach (var item in queryData)
{
	foreach (var entry in item)
	{
		Console.WriteLine($"ID: {entry.Id} | Distance: {entry.Distance}");
	}
}

The URI, the HttpClient and the use from more threads: Connecting.

Compatibility

docs/COMPATIBILITY.md lists every tested release, the differences between them and the versions the CI runs.

The compatibility table shows every check of the latest release on Chroma 1.5.9 and on Chroma Cloud, on each .NET runtime and platform.

Documentation

• Connecting: the URI, the HttpClient, threads, the API version, authentication and connection strings.
• Dependency injection: AddChromaClient and AddKeyedChromaClient.
• Collections: collections, tenants and databases, collections by id.
• Records: URIs, large writes, deletes and base64 embeddings.
• Metadata values: values, lists, deletions in updates and upserts, document copies, conversions.
• Queries and filters: queries, GetAsync in pages, where and document filters.
• Upsert strategies: Server and SkipUnchangedEmbeddings.
• Index settings: the distance, the HNSW and SPANN settings, ModifyConfigurationAsync.
• Errors: ChromaException and CollectionExistsAsync.
• Mocks in tests: mocking ChromaClient and ChromaCollectionClient.
• Health, traces and metrics: HealthcheckAsync and OpenTelemetry.
• Chroma Cloud: options, identity, batches, quotas and the operations of Chroma Cloud.
• Search: the Search API and hybrid search with BM25.
• Sparse vectors and schema: sparse vectors, BM25 indexes and the indexes of a schema.
• Platforms: the builds, trimming and NativeAOT.
• About this fork: the original project and what this fork does.

Migrating from ChromaDB.Client 1.x

The migration guide has the details, and the release notes list the changes of every version.

Contributing

CONTRIBUTING.md and SECURITY.md.

License

The project is released under the MIT License, keeping the original copyright notice.