Implementation:Lance format Lance Java VectorIndexParams

Knowledge Sources	Lance
Domains	Java_SDK, Indexing
Last Updated	2026-02-08 19:33 GMT

Overview

Description

VectorIndexParams is a Java class in the org.lance.index.vector package that aggregates all parameters for creating a vector index in Lance. It combines a DistanceType, required IvfBuildParams, and optional PQBuildParams, HnswBuildParams, and SQBuildParams. The class enforces two validation rules: PQ and SQ cannot coexist, and HNSW must be combined with either PQ or SQ. It provides both a Builder pattern and convenient static factory methods for common index configurations.

Usage

VectorIndexParams is set on IndexParams via setVectorIndexParams() and ultimately consumed by IndexOptions when building a vector index. The static factory methods (ivfFlat, ivfPq, withIvfPqParams, withIvfHnswPqParams, withIvfHnswSqParams) provide concise shortcuts for the most common configurations.

Code Reference

Source Location

java/src/main/java/org/lance/index/vector/VectorIndexParams.java

Signature

public class VectorIndexParams {
    // Static factory methods
    public static VectorIndexParams ivfFlat(int numPartitions, DistanceType distanceType);
    public static VectorIndexParams ivfPq(
        int numPartitions, int numBits, int numSubVectors,
        DistanceType distanceType, int maxIterations);
    public static VectorIndexParams withIvfPqParams(
        DistanceType distanceType, IvfBuildParams ivf, PQBuildParams pq);
    public static VectorIndexParams withIvfHnswPqParams(
        DistanceType distanceType, IvfBuildParams ivf,
        HnswBuildParams hnsw, PQBuildParams pq);
    public static VectorIndexParams withIvfHnswSqParams(
        DistanceType distanceType, IvfBuildParams ivf,
        HnswBuildParams hnsw, SQBuildParams sq);

    // Accessors
    public DistanceType getDistanceType();
    public String getDistanceTypeString();
    public IvfBuildParams getIvfParams();
    public Optional<PQBuildParams> getPqParams();
    public Optional<HnswBuildParams> getHnswParams();
    public Optional<SQBuildParams> getSqParams();

    public static class Builder {
        public Builder(IvfBuildParams ivfParams);
        public Builder setDistanceType(DistanceType distanceType);
        public Builder setPqParams(PQBuildParams pqParams);
        public Builder setHnswParams(HnswBuildParams hnswParams);
        public Builder setSqParams(SQBuildParams sqParams);
        public VectorIndexParams build();
    }
}

Import

import org.lance.index.vector.VectorIndexParams;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
ivfParams	IvfBuildParams	Yes	N/A	IVF partitioning parameters (required constructor argument)
distanceType	DistanceType	No	DistanceType.L2	Distance metric for similarity computation
pqParams	PQBuildParams	No	Optional.empty()	Product quantization parameters (mutually exclusive with SQ)
hnswParams	HnswBuildParams	No	Optional.empty()	HNSW graph parameters (requires PQ or SQ)
sqParams	SQBuildParams	No	Optional.empty()	Scalar quantization parameters (mutually exclusive with PQ)

Validation Rules

Rule	Exception
PQ and SQ cannot both be present	IllegalArgumentException("PQ and SQ cannot coexist")
HNSW requires either PQ or SQ	IllegalArgumentException("HNSW must be combined with either PQ or SQ")

Static Factory Methods

Method	Index Type	Parameters
ivfFlat()	IVF_FLAT	numPartitions, distanceType
ivfPq()	IVF_PQ	numPartitions, numBits, numSubVectors, distanceType, maxIterations
withIvfPqParams()	IVF_PQ	distanceType, IvfBuildParams, PQBuildParams
withIvfHnswPqParams()	IVF_HNSW_PQ	distanceType, IvfBuildParams, HnswBuildParams, PQBuildParams
withIvfHnswSqParams()	IVF_HNSW_SQ	distanceType, IvfBuildParams, HnswBuildParams, SQBuildParams

Usage Examples

import org.lance.index.vector.*;
import org.lance.index.DistanceType;
import org.lance.index.IndexParams;

// 1. Quick IVF-Flat index
VectorIndexParams ivfFlat = VectorIndexParams.ivfFlat(256, DistanceType.L2);

// 2. Quick IVF-PQ index
VectorIndexParams ivfPq = VectorIndexParams.ivfPq(
    256, 8, 16, DistanceType.Cosine, 50
);

// 3. Full control with IVF + PQ
IvfBuildParams ivf = new IvfBuildParams.Builder()
    .setNumPartitions(128)
    .setSampleRate(512)
    .build();
PQBuildParams pq = new PQBuildParams.Builder()
    .setNumSubVectors(32)
    .setMaxIters(100)
    .build();
VectorIndexParams fullPq = VectorIndexParams.withIvfPqParams(
    DistanceType.Dot, ivf, pq
);

// 4. IVF + HNSW + SQ
HnswBuildParams hnsw = new HnswBuildParams.Builder()
    .setM(32)
    .setEfConstruction(200)
    .build();
SQBuildParams sq = new SQBuildParams.Builder().build();
VectorIndexParams hnswSq = VectorIndexParams.withIvfHnswSqParams(
    DistanceType.L2, ivf, hnsw, sq
);

// 5. Use via Builder for maximum control
VectorIndexParams custom = new VectorIndexParams.Builder(ivf)
    .setDistanceType(DistanceType.Cosine)
    .setPqParams(pq)
    .setHnswParams(hnsw)
    .build();

// Wrap in IndexParams
IndexParams params = IndexParams.builder()
    .setVectorIndexParams(hnswSq)
    .build();

Related Pages

• IvfBuildParams - Required IVF partitioning parameters
• PQBuildParams - Optional product quantization parameters
• SQBuildParams - Optional scalar quantization parameters
• HnswBuildParams - Optional HNSW graph parameters
• DistanceType - Distance metric enum
• IndexParams - Top-level container that holds VectorIndexParams
• IndexOptions - Consumes IndexParams for index creation