Precompute query-to-reference nearest neighbors — precompute_query

precompute_query_knn() searches a fixed reference matrix for every row of a query matrix. It uses the same package-native backend family and routing policy as precompute_knn(), but does not compute unnecessary reference-to-reference or query-to-query neighbors.

Usage

precompute_query_knn(
  reference,
  query,
  k = 30L,
  metric = c("euclidean", "cosine", "correlation"),
  backend = NULL,
  n.cores = NULL
)

Arguments

reference: Reference observations in rows.
query: Query observations in rows and the same feature space as reference.
k: Number of non-self nearest neighbors to return.
metric: Distance metric: "euclidean", "cosine", or "correlation".
backend: Search backend: "cpu", "cuda", or "metal".
n.cores: Number of CPU cores. Native GPU backends ignore this argument.

Value

A fastEmbedR_knn object with one row per query observation and one-based indices into reference.

Details

CPU uses exhaustive reference-query search when the reference has fewer than 5,000 rows and HNSW otherwise. HNSW uses metric-, shape-, and k-aware target-0.99 parameters and does not claim a per-call recall audit. tuning_reference_target_met describes the faissR calibration cell and is not measured recall for the current call. Metal routes between a native query-only exact kernel and recall-tuned IVF-Flat from the estimated reference-query distance workload. CUDA routes between cuVS brute-force exact search and cuVS IVF-Flat using the reference size, query batch size, and feature count. CUDA results remain device-resident for direct consumption by landmark UMAP and t-SNE transformations.

Examples

x <- scale(as.matrix(iris[, 1:4]))
ref <- x[1:100, , drop = FALSE]
qry <- x[101:150, , drop = FALSE]
knn <- precompute_query_knn(ref, qry, k = 10, backend = "cpu")