Rcpp bindings for hnswlib, a header-only C++ library for finding approximate nearest neighbors using hierarchical navigable small-world graphs (Malkov and Yashunin, 2020).
From CRAN:
install.packages("RcppHNSW")Development versions from GitHub:
pak::pak("jlmelville/RcppHNSW")| Task | Interface | Reference |
|---|---|---|
| Find neighbors within one matrix | hnsw_knn() |
hnsw_knn help |
| Build an index for later searches | hnsw_build() |
hnsw_build help |
| Search an existing index | hnsw_search() |
hnsw_search help |
| Control index construction and lifecycle directly | HnswL2, HnswEuclidean, HnswCosine, or HnswIp |
Module API and index lifecycle |
irism <- as.matrix(iris[, -5])
# returns neighbor indices and distances in two n x k matrices
iris_knn <- RcppHNSW::hnsw_knn(irism, k = 4, distance = "euclidean")
dim(iris_knn$idx)The process can also be split into two steps, so you can build with one set of
data and search with another. See hnsw_build()
and hnsw_search().
distance |
Distance calculated |
|---|---|
"l2" |
Squared L2, i.e. squared Euclidean. |
"euclidean" |
Euclidean. |
"cosine" |
One minus cosine similarity. |
"ip" |
One minus inner product: 1 - sum(a * b). Values can be negative and need not satisfy metric properties. |
- HNSW search is approximate, so even a zero-distance self-match may be absent. Inner-product distance does not guarantee self-matches.
- Coordinates are stored as single-precision floats. The package rejects non-finite or out-of-range coordinates and zero-norm cosine vectors.
- Items are stored by row by default. Column-oriented data and the corresponding result shapes are described in the parameters, metrics, and data-layout guide.
- Index construction uses hnswlib's
random_seed;set.seed()has no effect. Parallel construction may be nondeterministic even with a fixed seed. - Module labels are one-based and follow insertion order.
kmust be positive and cannot exceed the active (not deleted) item count. If an exception escapes after insertion has begun, the index becomes unusable and must be discarded and rebuilt or reloaded. - The Module
ann$save()method writes hnswlib's raw checkpoint format. Compatibility depends on the hnswlib version and platform. See the Module API and index-lifecycle guide.
Function reference:
Guides:
RcppHNSW was inspired by RcppAnnoy, which provides an R interface to the Annoy library.
See NEWS for release and development changes. Source and issue tracking are on GitHub.