ChromaDotNet.VectorData 0.3.2

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. .NET Framework 4.6.2 This package targets .NET Framework 4.6.2. The package is compatible with this framework or higher. 
dotnet add package ChromaDotNet.VectorData --version 0.3.2
                    


                    

                
NuGet\Install-Package ChromaDotNet.VectorData -Version 0.3.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ChromaDotNet.VectorData" Version="0.3.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ChromaDotNet.VectorData" Version="0.3.2" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ChromaDotNet.VectorData" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ChromaDotNet.VectorData --version 0.3.2
                    


                    

                
#r "nuget: ChromaDotNet.VectorData, 0.3.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ChromaDotNet.VectorData@0.3.2
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ChromaDotNet.VectorData&version=0.3.2
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ChromaDotNet.VectorData&version=0.3.2
                    


                            Install as a Cake Tool

ChromaDotNet.VectorData

Chroma provider for Microsoft.Extensions.VectorData, built on ChromaDotNet.Client.

This is a community project. It is not affiliated with or endorsed by Chroma.

Quick start

  1. Run Chroma with Docker:
docker run -d --name chroma -p 8000:8000 chromadb/chroma:1.5.9
  1. Install the NuGet package:
dotnet add package ChromaDotNet.VectorData
  1. Store and search records:
using ChromaDB.Client;
using ChromaDB.VectorData;
using Microsoft.Extensions.VectorData;

using var httpClient = new HttpClient();
var client = new ChromaClient(new ChromaConfigurationOptions("http://localhost:8000"), httpClient);
using var vectorStore = new ChromaVectorStore(client);

var collection = vectorStore.GetCollection<string, Hotel>("hotels");
await collection.EnsureCollectionExistsAsync();

await collection.UpsertAsync(new Hotel { Id = "h1", Name = "Grand", Rating = 5, Embedding = new float[] { 0.1f, 0.2f, 0.3f, 0.4f } });

await foreach (var result in collection.SearchAsync(new float[] { 0.1f, 0.2f, 0.3f, 0.4f }, top: 3, new() { Filter = h => h.Rating >= 4 }))
{
    Console.WriteLine($"{result.Record.Name}: {result.Score}");
}

public sealed class Hotel
{
    [VectorStoreKey]
    public string Id { get; set; } = "";

    [VectorStoreData(IsFullTextIndexed = true)]
    public string? Name { get; set; }

    [VectorStoreData]
    public int Rating { get; set; }

    [VectorStoreVector(4)]
    public ReadOnlyMemory<float> Embedding { get; set; }
}

With dependency injection, the vector store takes the ChromaClient of the container, like the singleton that ChromaDotNet.Client.DependencyInjection registers with an HttpClient from IHttpClientFactory:

// dotnet add package ChromaDotNet.Client.DependencyInjection
using ChromaDB.Client;
using ChromaDB.Client.DependencyInjection;

services.AddChromaClient(_ => new ChromaConfigurationOptions("http://localhost:8000"));
services.AddChromaVectorStore();

Or it creates its own client, from a URI or from the options of the client, like those of Chroma Cloud:

services.AddChromaVectorStore("http://localhost:8000");

services.AddChromaVectorStore(new ChromaConfigurationOptions("https://api.trychroma.com", tenant: "<tenant>", database: "<database>")
    .WithChromaToken("<api key>"));

AddChromaCollection<TKey, TRecord>(name, …) registers one collection in the same three ways, and AddKeyedChromaVectorStore and AddKeyedChromaCollection register them under a key. With these registrations, the embedding generator is the EmbeddingGenerator of ChromaVectorStoreOptions or ChromaCollectionOptions, or else an IEmbeddingGenerator registered in the container. Without dependency injection, ChromaVectorStore and ChromaCollection also take the options of the client with an HttpClient, which they dispose with ownsClient: true. GetService(typeof(ChromaClient)) on the vector store or a collection returns the client it uses.

Chroma Cloud

Connect with the options of the client: the API key goes in the X-Chroma-Token header, with the tenant and the database of the Chroma Cloud dashboard. Chroma Cloud reads and writes at most 300 records per request: on its addresses the client writes and reads in batches of 300 by itself. A search returns at most 300 results, top plus Skip included.

On Chroma Cloud, HybridSearchAsync searches with a vector and keywords together: it fuses the ranks of the vector search and of a BM25 search of the keywords in a full-text indexed string property. The BM25 search needs a BM25 index, a sparse vector index of Chroma, on the text of the property. With CreateBm25Indexes, creating the collection creates one for each full-text indexed string property, like Name of Hotel above, and the client computes the BM25 vectors of the records as it writes them:

var collection = new ChromaCollection<string, Hotel>(client, "hotels-hybrid", new() { CreateBm25Indexes = true });
await collection.EnsureCollectionExistsAsync();

var results = collection.HybridSearchAsync(new float[] { 0.1f, 0.2f, 0.3f, 0.4f }, ["pool", "spa"], top: 5);

ChromaVectorStoreOptions has the same option for the collections of a vector store. Only with the option, and a full-text indexed string property, a collection answers IKeywordHybridSearchable from GetService, which the TextSearchStore of Semantic Kernel asks for to choose hybrid search over vector search. AddChromaCollection registers the collection as IKeywordHybridSearchable<TRecord> in any case: resolve it from the container only with the option. The score of a hybrid result is the reciprocal rank fusion score (k = 60) of the two searches: higher is better, well below 1, and ScoreThreshold applies to it. A collection created by another client of Chroma, like the Python one, works too when it has a chroma_bm25 index on the text of the property, or on the documents for the property stored as the document. A record without any of the keywords gets nothing from the BM25 search, as in a keyword search. A single Chroma server has neither the Search API nor sparse vector indexes.

Supported

  • Keys: string and Guid.
  • One vector per record: ReadOnlyMemory<float>, Embedding<float> or float[], or any type with an embedding generator.
  • Data properties: string, int, long, double, float, bool, DateTime, DateTimeOffset, DateOnly (.NET 8 and later), their nullable forms, and arrays or List<T> of the non-nullable ones, stored as Chroma metadata; dates are stored as ISO 8601 strings.
  • Targets .NET 10, .NET 8, .NET Standard 2.0 and .NET Framework 4.6.2; NativeAOT needs .NET 8 or later.
  • Distance functions: CosineSimilarity (the default), CosineDistance, DotProductSimilarity, NegativeDotProductSimilarity, EuclideanDistance and EuclideanSquaredDistance, with the HNSW index.
  • An existing collection must use the space of the distance function, as a collection created by another Chroma client without a space uses l2: otherwise the provider throws, rather than turning the distances of another space into scores.
  • Filters: == and !=, <, <=, > and >= on numbers, &&, ||, !, Contains over an inline list or an array property, and Any with Contains over an inline list.
  • Filters on the key: == and Contains over a list of keys, joined to the other conditions with &&; Chroma looks the records up by id.
  • Full-text: the only full-text indexed string property is also stored as the Chroma document, where other Chroma clients store their text. Contains and !Contains on it filter the text with where_document, joined to the other conditions with &&, and a record that has its text in the document only reads it into that property.
  • NativeAOT and trimming: the dynamic collection, from GetDynamicCollection with a VectorStoreCollectionDefinition, works without reflection; ChromaCollection<TKey, TRecord> maps the properties of the record type by reflection. The AddChroma… registration methods are marked as incompatible with trimming and NativeAOT: there, register the vector store yourself, like services.AddSingleton<VectorStore>(sp => new ChromaVectorStore(sp.GetRequiredService<ChromaClient>()));.

Limitations

  • Chroma metadata has no null values: a null property is not stored, and filtering on null is not supported.
  • Chroma does not store empty lists: an empty array or list is not stored, and comes back as null.
  • GetAsync with a filter does not support ordering.
  • Comparisons work on numbers only.
  • Array properties need Chroma 1.5.0 or later.
  • Hybrid search needs Chroma Cloud.
  • Only one property can be the document: with more full-text indexed string properties, none is.

The provider runs the Microsoft.Extensions.VectorData conformance tests in CI against Chroma 1.5.0, 1.5.9 and the latest release; on Chroma Cloud, hybrid search included, they are run by hand and pass.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.3.2 0 10/5/2026
0.3.1 0 10/5/2026
0.3.0 0 10/5/2026
0.2.0 30 10/4/2026
0.1.2 35 10/4/2026
0.1.0 42 10/4/2026

0.3.2: the vector store registers with dependency injection also with NativeAOT and trimming, and the warnings of the collection registrations name the way that works there, the dynamic collection; the README of the package describes the registrations, the score of hybrid search and the supported types. 0.3.1: a collection offers hybrid search through GetService only with CreateBm25Indexes, where it can work: the TextSearchStore of Semantic Kernel, which chooses hybrid search through GetService, searches by vector again elsewhere, as with 0.2.0. 0.3.0: hybrid search on Chroma Cloud: HybridSearchAsync fuses the ranks of the vector search and of a BM25 search of the keywords; CreateBm25Indexes creates a BM25 index for each full-text indexed string property, and collections created by other Chroma clients with a chroma_bm25 index work too; it needs ChromaDotNet.Client 2.8.0, which reads in pages and writes in batches on Chroma Cloud by itself. 0.2.0: registration with the options of the client, like those of Chroma Cloud; reads in pages of the batch size of the client; the full-text property is also stored as the Chroma document, and Contains on it filters its text. 0.1.2: full-text indexed properties are accepted, as Semantic Kernel and Agent Framework declare them; filters on the key; an existing collection with another space throws instead of giving wrong scores; empty lists are not stored; Contains over an empty list matches no record; a collection created again elsewhere is looked up again. 0.1.0: the first release. All the releases: https://github.com/ChromaDotNet/ChromaDB.VectorData/releases