ChromaDotNet.Client

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.
  • Used by:
    • Generative AI for Beginners .NET: a RAG sample in the Microsoft course.
    • LangChain .NET: a RAG sample with Chroma.
    • LangChain.Databases: the integration tests.
  • Cited in:
    • Semantic Kernel: recommended for Chroma in .NET.
    • LangChain.Databases: recommended for Chroma in its README.
    • Microsoft Agent Framework: listed among the .NET community projects.
• CommunityToolkit.Aspire.Chroma: the Chroma client integration, in the Aspire Community Toolkit of the .NET Foundation.
• BotSharp.Plugin.Chroma: the Chroma vector database plugin of BotSharp, by SciSharp.
• LlmTornado.VectorDatabases.ChromaDB: the Chroma connector of LLM Tornado.

Try it in your browser

Click Open in GitHub Codespaces above. The Codespace has .NET 10 and Chroma on port 8000. When the terminal is ready, run:

dotnet run Samples/quickstart.cs

The quickstart takes ChromaDotNet.Client from NuGet, creates a collection, adds records with documents and metadata, queries them by similarity and by metadata, and deletes the collection. The embeddings are written by hand, so no model or key is needed.

You need a GitHub account. The Codespace uses the free Codespaces hours of your account.

Installation

dotnet add package ChromaDotNet.Client

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

To run Chroma on your machine without Docker: ChromaDotNet.Local.

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.
• Embeddings: embeddings from an IEmbeddingGenerator, query texts and the default embedding function of Chroma.
• 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.