Experimental file-backed query-to-landmark nearest neighbors

Searches a disk-backed matrix in bounded query batches. The default search keeps the landmark reference in RAM or VRAM. Explicit CPU stream_exact scans bounded reference blocks without materializing the full landmark matrix; this exact route is quadratic in query and landmark counts. CPU exact and HNSW, and CUDA exact or IVF-Flat search retain their native references across query batches. CUDA requires native cuVS support. IVF-Flat calibrates on the first query batch; the pilot recall is not a guarantee for all remaining rows. For CUDA IVF, pilot_recall counts distance-equivalent ties at the exact kth distance; pilot_id_recall reports strict neighbor-ID overlap. CPU uses exact search by default below 5,000 landmarks. Output files contain row-major, one-based uint32 landmark indices and float32 distances. HNSW's 0.99 recall is a target, not a measured result. Explicit CUDA sharded_exact builds one bounded reference shard at a time and merges exact candidates on disk. It rereads every query for each shard and can be much slower than an in-VRAM index.

Usage

massive_landmark_knn(
  x,
  reference,
  k,
  output,
  backend = "cpu",
  n.cores = 1L,
  method = c("auto", "exact", "stream_exact", "hnsw", "ivf", "sharded_exact"),
  chunk_rows = NULL,
  reference_chunk_rows = NULL,
  memory_limit = "8GB",
  checkpoint = FALSE,
  resume = FALSE,
  devices = NULL
)

Arguments

x

Query massive_matrix() descriptor.

reference

Landmark massive_matrix() descriptor or the result of massive_select_landmarks().

k

Number of nearest landmarks.

output

New file prefix for .indices.u32 and .distances.f32.

backend

"cpu" or "cuda"; CUDA never falls back to CPU.

n.cores

CPU worker count.

method

"auto", "exact", "stream_exact" (CPU with a file-backed reference), "hnsw" (CPU), "ivf" (CUDA), or "sharded_exact" (CUDA with a file-backed reference).

chunk_rows

Maximum query rows per batch.

reference_chunk_rows

Maximum reference rows per batch for "stream_exact" or "sharded_exact"; otherwise must be NULL.

memory_limit

Conservative RAM budget. CUDA also caps batches to a conservative fraction of currently free VRAM.

checkpoint

Save completed KNN batches to a sidecar file.

resume

Continue from matching partial KNN files and checkpoint. Sharded exact CUDA search commits every 100 query blocks and at each reference-shard boundary.

devices

Optional CUDA device indices. Multiple devices search disjoint query ranges, including with sharded_exact. Checkpointing requires file-backed query and reference sources.

Value

A lightweight fastEmbedR_massive_knn descriptor.