Skip to contents

Build a nearest neighbor index

Source: R/hnsw.R
hnsw_build.Rd

Build an HNSW index that you can keep and query with hnsw_search().

Usage

hnsw_build(
  X,
  distance = "euclidean",
  M = 16,
  ef = 200,
  verbose = FALSE,
  progress = "bar",
  n_threads = 0,
  grain_size = 1,
  byrow = TRUE,
  random_seed = 100
)

Arguments

X

Numeric matrix to index, with one item per row, or per column when byrow = FALSE.

distance

Distance to use:

  • "euclidean": Euclidean distance.

  • "l2": squared Euclidean distance.

  • "cosine": one minus cosine similarity.

  • "ip": one minus inner product, 1 - sum(a * b); can be negative.

M

Number of graph links per item during construction. Larger values improve connectivity and use more memory. Must be between 2 and 10000.

ef

Candidate-list size during construction. Larger values improve index quality and increase build time. Must be a positive whole number and is not capped at the dataset size. This is the ef_construction parameter of hnsw_knn().

verbose

If TRUE, log messages to the console.

progress

Unused; retained for compatibility.

n_threads

Maximum number of threads for batch insertion or search. Zero (the default) and one run serially.

grain_size

Minimum number of items per thread. Larger values limit threading overhead for small batches. Zero is treated as one.

byrow

If TRUE, items are rows of X; otherwise, they are columns.

random_seed

Seed for hnswlib's index construction. R's set.seed() has no effect. Use serial construction for repeatable builds; parallel insertion order can vary with a fixed seed.

Value

An HnswEuclidean, HnswL2, HnswCosine, or HnswIp index, according to distance. Labels are one-based and follow the order in X.

Details

Coordinates are stored in single precision; see RcppHnsw-package for numeric limits. If you want to add more items, resize, or save the index, see the Module guide for the available methods.

See also

hnsw_knn() to build and search in one call.

Examples

irism <- as.matrix(iris[, -5])
ann <- hnsw_build(irism[1:100, ])
neighbors <- hnsw_search(irism[101:150, ], ann, k = 5)