HNSW 26.9.5494

<a href="https://curiosity.ai"><img src="https://curiosity.ai/media/cat.color.square.svg" width="100" height="100" align="right" /></a>

HNSW.Net

.Net library for fast approximate nearest neighbours search.

Exact k nearest neighbours search algorithms tend to perform poorly in high-dimensional spaces. To overcome curse of dimensionality the ANN algorithms come in place. This library implements one of such algorithms described in the "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs" article. It provides simple API for building nearest neighbours graphs, (de)serializing them and running k-NN search queries.

Usage

Check out the following code snippets once you've added the library reference to your project.

How to build a graph?

var parameters = new SmallWorld<float[], float>.Parameters()
{
  M = 15,
  LevelLambda = 1 / Math.Log(15),
  EfSearch = 50,
};

float[] vectors = GetFloatVectors();
var graph = new SmallWorld<float[], float>(CosineDistance.NonOptimized);
graph.BuildGraph(vectors, new Random(42), parameters);

How to run k-NN search?

SmallWorld<float[], float> graph = GetGraph();

float[] query = Enumerable.Repeat(1f, 100).ToArray();
var best20 = graph.KNNSearch(query, 20);
var best1 = best20.OrderBy(r => r.Distance).First();

How to speed up search with early termination?

KNN search can stop traversing the graph once the result set has stopped improving, trading a little recall for fewer distance computations (see the Manticore write-up and "Patience in Proximity", Teofili & Lin, ECIR 2025). The savings grow with k and EfSearch. It is disabled by default.

var parameters = new SmallWorld<float[], float>.Parameters()
{
  EfSearch = 100,
  EnableEarlyTermination = true,             // turn the optimization on
  EarlyTerminationSaturationThreshold = 0.95, // optional: fraction of top-k left unchanged to count a hop as "non-improving"
  EarlyTerminationPatience = 0,               // optional: consecutive non-improving hops before stopping (0 = adaptive, scales with EfSearch)
};

How to (de)serialize the graph?

The graph is written without its items - the caller keeps those and hands them back on load, in the same order. Items the persisted graph does not cover come back as ItemsNotInGraph, so a crash between "items persisted" and "graph persisted" is recovered by re-adding them.

SmallWorld<float[], float> graph = GetGraph();
graph.OptimizeIfNeeded();          // flattens the connections; optional, but makes the write a span copy
graph.SerializeGraph(stream);      // parameters + edges, nothing else

// distance function must be the same as the one which was used for building the original graph
var (copy, itemsNotInGraph) = SmallWorld<float[], float>.DeserializeGraph(vectors, CosineDistance.NonOptimized, DefaultRandomGenerator.Instance, stream);
copy.AddItems(itemsNotInGraph);

There is also an IBufferWriter<byte> overload, for a caller that already has a pooled writer and a destination that takes a contiguous span (a key-value store's put, an encryption call):

var writer = new ArrayBufferWriter<byte>();
graph.SerializeGraph(writer);
db.Put(key, writer.WrittenSpan);

Format. Graphs are written in the flat HNSW2 format: a msgpack header and parameters, then each node's connections as one run of little-endian ints - the per-layer start offsets, the total, then the neighbour ids. That is byte for byte how the connections are already held in memory once the graph is flattened, so a save is a span copy per node and a load is a span fill per node, through a buffer rented from ArrayPool<byte>.Shared. Nothing is staged in memory at graph size and no per-node list is allocated in either direction. The older HNSW (MessagePack) format is still read, so existing files keep loading.

Distance functions

The only one distance function supplied by the library is the cosine distance. But there are 4 versions to address universality/performance tradeoff.

CosineDistance.NonOptimized // most generic version works for all cases
CosineDistance.ForUnits     // gives correct result only when arguments are "unit" vectors
CosineDistance.SIMD         // uses SIMD instructions to optimize calculations
CosineDistance.SIMDForUnits // uses SIMD and requires arguments to be "units"

But the API allows to inject any custom distance function tailored specifically for your needs.

Contributing

Your contributions and suggestions are very welcome! Please note that this project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

The contributions to this project are released to the public under the project's open source license. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

How to contribute

If you've found a bug or have a feature request then please open an issue with detailed description. We will be glad to see your pull requests as well.

1. Prepare workspace.

git clone https://github.com/Microsoft/HNSW.Net.git
cd HNSW.Net
git checkout -b [username]/[feature]

2. Update the library and add tests if needed.
3. Build and test the changes.

cd Src
dotnet build
dotnet test

4. Send the pull request from [username]/[feature] to master branch.
5. Get approve and merge the changes.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

Releasing

The library is distributed as a bundle of sources. We are working on enabling CI and creating Nuget package for the project.