Implementation:Lance format Lance VectorIndexParams

Knowledge Sources	Lance
Domains	Vector_Search, Indexing
Last Updated	2026-02-08 19:00 GMT

Overview

Concrete tool for specifying vector index build parameters provided by the Lance library.

Description

VectorIndexParams is the configuration struct that defines the algorithmic stages, distance metric, and file format version for building a Lance vector index. It implements the IndexParams trait and is passed to CreateIndexBuilder or Dataset::create_index.

The struct contains a Vec<StageParams> pipeline where each element selects and configures one stage of the index (IVF, HNSW, PQ, SQ, or RQ). Several convenience constructors are provided for common index type combinations.

Usage

Use this struct when you need to:

• Configure parameters for a new vector index before calling create_index.
• Tune IVF partition counts, HNSW graph parameters, or quantization settings.
• Select a specific composite index type (IVF_PQ, IVF_HNSW_PQ, IVF_HNSW_SQ, etc.).

Code Reference

Source Location

• Repository: Lance
• File: rust/lance/src/index/vector.rs
• Lines: L69-L76 (StageParams enum), L101-L110 (VectorIndexParams struct), L145 (ivf_pq), L221 (ivf_hnsw), L236 (with_ivf_hnsw_pq_params), L256 (with_ivf_hnsw_sq_params)

Signature

#[derive(Debug, Clone)]
pub struct VectorIndexParams {
    pub stages: Vec<StageParams>,
    pub metric_type: MetricType,
    pub version: IndexFileVersion,
}

#[derive(Debug, Clone)]
pub enum StageParams {
    Ivf(IvfBuildParams),
    Hnsw(HnswBuildParams),
    PQ(PQBuildParams),
    SQ(SQBuildParams),
    RQ(RQBuildParams),
}

Import

use lance::index::vector::{VectorIndexParams, StageParams};
use lance_index::vector::ivf::IvfBuildParams;
use lance_index::vector::hnsw::builder::HnswBuildParams;
use lance_index::vector::pq::PQBuildParams;
use lance_index::vector::sq::SQBuildParams;
use lance_linalg::distance::MetricType;

I/O Contract

Inputs

Name	Type	Required	Description
stages	Vec<StageParams>	Yes	Ordered pipeline of index algorithm stages. Common combinations: [Ivf, PQ] for IVF_PQ; [Ivf, Hnsw, PQ] for IVF_HNSW_PQ.
metric_type	MetricType	Yes	Distance metric: MetricType::L2, MetricType::Cosine, or MetricType::Dot.
version	IndexFileVersion	Yes	Index file format version. V3 for all modern index types; Legacy for older IVF_PQ only.

IvfBuildParams (key fields)

Name	Type	Default	Description
num_partitions	usize	--	Number of IVF clusters. Typically sqrt(n) to 4*sqrt(n).
max_iters	usize	50	Maximum k-means iterations for centroid training.
sample_rate	usize	256	Ratio of training samples to number of centroids.
centroids	Option<FixedSizeListArray>	None	Pre-trained centroids. If provided, k-means training is skipped.

HnswBuildParams (key fields)

Name	Type	Default	Description
max_level	u16	7	Maximum number of layers in the HNSW graph.
m	usize	20	Number of bi-directional edges per node.
ef_construction	usize	150	Size of dynamic candidate list during graph construction.
prefetch_distance	Option<usize>	Some(2)	Prefetch distance for I/O optimization.

PQBuildParams (key fields)

Name	Type	Default	Description
num_sub_vectors	usize	16	Number of sub-vector partitions for product quantization.
num_bits	usize	8	Bits per sub-quantizer (256 centroids when 8).
max_iters	usize	50	Maximum training iterations for PQ codebook.
sample_rate	usize	256	Training sample ratio.

SQBuildParams (key fields)

Name	Type	Default	Description
num_bits	u16	8	Bits per scalar quantization bucket.
sample_rate	usize	256	Training sample ratio.

Outputs

Name	Type	Description
(self)	VectorIndexParams	A fully configured parameter object ready to be passed to CreateIndexBuilder::new or Dataset::create_index.

Usage Examples

Creating IVF_PQ parameters

use lance::index::vector::VectorIndexParams;
use lance_linalg::distance::MetricType;

let params = VectorIndexParams::ivf_pq(
    256,              // num_partitions
    8,                // num_bits
    16,               // num_sub_vectors
    MetricType::L2,   // metric
    50,               // max_iterations
);

Creating IVF_HNSW_SQ parameters with fine-grained control

use lance::index::vector::VectorIndexParams;
use lance_index::vector::ivf::IvfBuildParams;
use lance_index::vector::hnsw::builder::HnswBuildParams;
use lance_index::vector::sq::SQBuildParams;
use lance_linalg::distance::MetricType;

let ivf = IvfBuildParams::new(512);
let hnsw = HnswBuildParams::default();
let sq = SQBuildParams::default();

let params = VectorIndexParams::with_ivf_hnsw_sq_params(
    MetricType::Cosine,
    ivf,
    hnsw,
    sq,
);

Creating IVF_HNSW_PQ parameters

use lance::index::vector::VectorIndexParams;
use lance_index::vector::ivf::IvfBuildParams;
use lance_index::vector::hnsw::builder::HnswBuildParams;
use lance_index::vector::pq::PQBuildParams;
use lance_linalg::distance::MetricType;

let ivf = IvfBuildParams::new(1024);
let hnsw = HnswBuildParams::default();
let pq = PQBuildParams::default();

let params = VectorIndexParams::with_ivf_hnsw_pq_params(
    MetricType::Cosine,
    ivf,
    hnsw,
    pq,
);

Related Pages

Implements Principle

• Principle:Lance_format_Lance_Vector_Index_Configuration

Requires Environment

• Environment:Lance_format_Lance_Rust_Toolchain
• Environment:Lance_format_Lance_SIMD_And_Platform_Requirements

Uses Heuristic

• Heuristic:Lance_format_Lance_Vector_Index_Tuning