Heuristic:Lance format Lance Vector Index Tuning

Knowledge Sources	Lance FAISS Library Lance Core Team
Domains	Vector_Search, Optimization
Last Updated	2026-02-08 19:00 GMT

Overview

Default vector index parameters for HNSW (m=20, ef_construction=150) and IVF (sample_rate=256, max_iters=50) balancing recall quality against build time and memory.

Description

Lance supports two primary vector index types: IVF (Inverted File Index) for partition-based search and HNSW (Hierarchical Navigable Small World) for graph-based search. Both have tunable parameters that trade off index build time, memory usage, and search recall quality. The defaults are derived from the FAISS library conventions and HNSW paper recommendations, tuned for Lance's columnar storage format.

Usage

Apply this heuristic when building vector indices, tuning search recall, or troubleshooting low recall results. If recall is too low, increase `ef_construction` (for HNSW) or `nprobes` (for IVF). If index building is too slow, reduce `sample_rate` or `max_iters`. If memory is constrained, reduce `m` (HNSW connections) or `max_partitions` (IVF).

The Insight (Rule of Thumb)

HNSW Parameters

max_level: 7 (supports up to 2^7 = 128 hierarchical levels)
m (connections): 20 bidirectional links per node
ef_construction: 150 candidate list size during build
prefetch_distance: 2 vectors ahead for cache optimization
Trade-off: Higher `m` and `ef_construction` improve recall but increase build time and memory. m=20 is a sweet spot for datasets up to tens of millions of vectors.

IVF Parameters

sample_rate: 256 (following FAISS conventions for KMeans training)
max_iters: 50 KMeans iterations for centroid convergence
max_partitions: 4,096 (avoids slow KMeans with too many clusters)
shuffle_partition_batches: 10,240 (1024 * 10)
shuffle_partition_concurrency: 2 parallel workers
Trade-off: Higher sample_rate improves centroid quality but increases training data size. More partitions give finer granularity but slower build.

Search-Time Parameters

XTR overfetch: 10x (configurable via `LANCE_XTR_OVERFETCH` env var) for exact-then-refine searches

Reasoning

The HNSW defaults (m=20, ef_construction=150) provide >95% recall for most datasets while keeping build time reasonable. The IVF sample_rate of 256 follows FAISS best practices, ensuring enough training data for stable KMeans convergence. The 4,096 partition cap prevents excessively slow KMeans clustering. The 10x XTR overfetch ensures high recall when refining approximate results with exact distance computation.

Warning: Sample rate >= 1024 with Float16 vectors can produce zero-valued centroids due to precision loss. This is logged as a warning at build time.

Code Evidence

HNSW defaults from `rust/lance-index/src/vector/hnsw/builder.rs:56-72`:

impl Default for HnswBuildParams {
    fn default() -> Self {
        Self {
            max_level: 7,
            m: 20,
            ef_construction: 150,
            prefetch_distance: Some(2),
        }
    }
}

IVF defaults from `rust/lance-index/src/vector/ivf/builder.rs:62-78`:

impl Default for IvfBuildParams {
    fn default() -> Self {
        Self {
            num_partitions: None,
            target_partition_size: None,
            max_iters: 50,
            centroids: None,
            retrain: false,
            sample_rate: 256,  // See faiss
            // ...
            shuffle_partition_batches: 1024 * 10,
            shuffle_partition_concurrency: 2,
        }
    }
}

XTR overfetch from `rust/lance/src/dataset/scanner.rs:142-150`:

const DEFAULT_XTR_OVERFETCH_VALUE: u32 = 10;

pub static DEFAULT_XTR_OVERFETCH: LazyLock<u32> = LazyLock::new(|| {
    parse_env_var(
        "LANCE_XTR_OVERFETCH",
        &DEFAULT_XTR_OVERFETCH_VALUE.to_string(),
    )
    .unwrap_or(DEFAULT_XTR_OVERFETCH_VALUE)
});

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment