hannoy 🗼

License Crates.io dependency status Build CodSpeed Badge

hannoy is a key-value backed HNSW implementation based on arroy.

Motivation

Many popular HNSW libraries are built in memory, meaning you need enough RAM to store all the vectors you're indexing. Instead, hannoy uses LMDB — a memory-mapped KV store — as a storage backend. This is more well-suited for machines running multiple programs, or cases where the dataset you're indexing won't fit in memory. LMDB also supports non-blocking concurrent reads by design, meaning its safe to query the index in multi-threaded environments.

Features

  • Supported metrics: euclidean, cosine, manhattan, hamming, as well as quantized counterparts.
  • Python bindings with maturin and pyo3
  • Multithreaded builds using rayon
  • Disk-backed storage to enable indexing datasets that won't fit in RAM using LMDB
  • Compressed bitmaps to store graph edges with minimal overhead, adding ~200 bytes per vector
  • Dynamic document insertions and deletions without full re-indexing

Missing Features

  • GPU-accelerated indexing

Usage

Rust 🦀

use hannoy::{distances::Cosine, Database, Reader, Result, Writer};
use heed::EnvOpenOptions;
use rand::{rngs::StdRng, SeedableRng};

fn main() -> Result<()> {
    let env = unsafe {
        EnvOpenOptions::new()
            .map_size(1024 * 1024 * 1024) // 1GiB
            .open("./")
    }
    .unwrap();

    let mut wtxn = env.write_txn()?;
    let db: Database<Cosine> = env.create_database(&mut wtxn, None)?;
    let writer: Writer<Cosine> = Writer::new(db, 0, 3);

    // build
    writer.add_item(&mut wtxn, 0, &[1.0, 0.0, 0.0])?;
    writer.add_item(&mut wtxn, 0, &[0.0, 1.0, 0.0])?;

    let mut rng = StdRng::seed_from_u64(42);
    let mut builder = writer.builder(&mut rng);
    builder.ef_construction(100).build::<16,32>(&mut wtxn)?;
    wtxn.commit()?;

    // search
    let rtxn = env.read_txn()?;
    let reader = Reader::<Cosine>::open(&rtxn, 0, db)?;

    let query = vec![0.0, 1.0, 0.0];
    let nns = reader.nns(1).ef_search(10).by_vector(&rtxn, &query)?.into_nns();

    dbg!("{:?}", &nns);
    Ok(())
}

Python 🐍

import hannoy
from hannoy import Metric
import tempfile

tmp_dir = tempfile.gettempdir()
db = hannoy.Database(tmp_dir, Metric.COSINE)

with db.writer(3, m=4, ef=10) as writer:
    writer.add_item(0, [1.0, 0.0, 0.0])
    writer.add_item(1, [0.0, 1.0, 0.0])

reader = db.reader()
nns = reader.by_vec([0.0, 1.0, 0.0], n=2)

(closest, dist) = nns[0]

Alternatively, you can add many items at once from a 2d numpy array of dtype float 32:

import numpy as np
with db.writer(3, m=4, ef=10) as writer:
    writer.add_items([0, 1], np.array([[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]], dtype=np.float32))

Tips and tricks

Reducing cold start latencies

Search in an hnsw always traverses from the top to bottom layers of the graph, so we know a priori some vectors will be needed. We can hint to the kernel that these vectors (and their neighbours) should be loaded into RAM using madvise to speed up search.

Doing so can reduce cold-start latencies by several milliseconds, and is configured through the HANNOY_READER_PREFETCH_MEMORY environment variable.

E.g. prefetching 10MiB of vectors into RAM.

export HANNOY_READER_PREFETCH_MEMORY=10485760

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nnethercott from gravatar.com nnethercott

Credits

Author: Kerollmops

Requires

Python >=3.9

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hannoy-0.1.3.tar.gz (1.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hannoy-0.1.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

hannoy-0.1.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.3 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64

hannoy-0.1.3-cp313-cp313-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

hannoy-0.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

hannoy-0.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.3 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64

hannoy-0.1.3-cp312-cp312-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

hannoy-0.1.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

hannoy-0.1.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.3 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64

hannoy-0.1.3-cp311-cp311-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

hannoy-0.1.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

hannoy-0.1.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.3 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ ARM64

hannoy-0.1.3-cp310-cp310-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file hannoy-0.1.3.tar.gz.

File metadata

  • Download URL: hannoy-0.1.3.tar.gz
  • Upload date:
  • Size: 1.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: maturin/1.14.1

File hashes

Hashes for hannoy-0.1.3.tar.gz
Algorithm Hash digest
SHA256 8e2742be21f0781dd27f85323c1a59f55df99b7fa38ffa3439fbf60a0faa82e6
MD5 c51f3c79f7214684781e958e06acde67
BLAKE2b-256 5126ea49e23cc2f35e0940bdd42199df2fc556f7dac1fd809846c6e950769942

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ac83a89d61cc6a780e9525e039cce2a321715e6dceb48e70c0eff6dc9a3fbea2
MD5 e06faf388068f14cb4471fefcee27e57
BLAKE2b-256 ce9e17d9ac88e2719633c503a031a4ec49cefba63e01fbda4162527cf283fabb

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 aa6e05a8ad17ad89f45aa67f8dc2c759eeb28a28beda0699335e4c1c081be831
MD5 b2fb3aaeedde54e8e42b5d14131f1f52
BLAKE2b-256 d13594e2e69a6a9b1bda7893a45becec23f8c4f1eb4472a6476cae8a1a115c9d

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0df862bce70f0caaa9df1446465a554e239d28f87b11657bb0b108b538c78eb8
MD5 a3695e93bfd17fc9691060b721cd2105
BLAKE2b-256 e7221024eff019cd47b8df7d006669fddf1ba5128fa29d7d92e5a048c86269b1

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 09fd96c9c4d6f5db3857fd50ac7d8b7e87bef254ffa067f730342da4f05480c1
MD5 38eee4c5ca96b8c86b45051a5c435a8b
BLAKE2b-256 ef9ad39518b24cd8d69caf57ccc479b96ef5600c3bb1e182de55fe2b7c069008

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 478fe968d162bacfd39b117618f93cd5526aeec207a19d9affb64099e330ce2e
MD5 3c6b2117413eb7b647b4174944fed6be
BLAKE2b-256 fa3f3c11ac7351120e8085351b7e15ec0b39ba6c23ba63706562bb62c3c93dcf

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 62dade88a318a75abf01789ee2f09cb50be9d6d37409aca36aac20e52195aae7
MD5 7ea5e2ea3c2400870a142cb526208188
BLAKE2b-256 da3c6221fb2d1b032164d0868dd76940f87783aefe5f329ba10df22fbd1271d6

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 43fec4c1c1baa7363fbdf919a00cd85121e6a1fc235ecad32c719e29fb5f77d7
MD5 8d2689137e3790abfc416e645d6d140a
BLAKE2b-256 7f6628076976db97a08a5e3b47fe04c6074680389a90ecd89405d78bb20593c8

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6ad568d00121acdbd7e9edf3ff3602ff3e9588e183131c5f3e1c35c12a5face8
MD5 1db861a3f37c64a14668758d01dd4d27
BLAKE2b-256 9858fd4ceeffe6c063586deb48d4f3119fc54275264a05e2a0d47cd6ba3909c3

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 89bb64c1e820e0a3e23c1cfda8a38f2cb62c6edea92e9b348ef930d04ab87b4e
MD5 3fd8579fec1988df4a1879b854965fca
BLAKE2b-256 56ea545d5d33f099e704b7720effd067ddf76114661622a694f6a7f38f29f09f

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 31743951220b0daaa986111d7bcb2c6e0149fc90d72cdf33d51b0ae1068161f8
MD5 5fb699eaef19c87b060a9690e76ff999
BLAKE2b-256 73c1cdf71fd73acd0abe6f0add8d8840fad8908707d9a453dcd306d272114657

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 95a60df06124578e80dfc33e6850879d1916e421bf2cdd108982ec575dcef338
MD5 b97cfba60688cca9067f543da9718ed6
BLAKE2b-256 d325f07d96bd631a40b2dad2a5cd2279fa0e885566622ec06ded73687ab01d1f

See more details on using hashes here.

File details

Details for the file hannoy-0.1.3-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hannoy-0.1.3-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f0ffddf4c15224e73d1c4416f2e9325e71be09c47f3267684e83dfea23a593b3
MD5 20a27d6e932ea31c7e74cac411b1a5e9
BLAKE2b-256 75e84a02a836cee8262c6fd7640294bf93794f6472290d6391b4d8871897e99e

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.1.3 This release

13 files

0.1.0

13 files

0.0.8

17 files

0.0.6

17 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page