Implementation:Lance format Lance Java HnswBuildParams

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

Overview

Description

HnswBuildParams is a Java class in the org.lance.index.vector package that defines parameters for building an HNSW (Hierarchical Navigable Small World) graph index within each IVF partition. HNSW graphs speed up nearest-neighbor search in large datasets by building a layered graph structure. The class is immutable and uses a Builder pattern with sensible defaults. Key parameters include the maximum number of graph levels, the number of edges per node (M), the construction-time exploration factor (efConstruction), and an optional prefetch distance for optimizing build performance.

Usage

HnswBuildParams is used as an optional component of VectorIndexParams when creating IVF+HNSW hybrid vector indices (IVF_HNSW_PQ, IVF_HNSW_SQ, IVF_HNSW_FLAT). It must be combined with either PQ or SQ quantization parameters.

Code Reference

Source Location

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

Signature

public class HnswBuildParams {
    public short getMaxLevel();
    public int getM();
    public int getEfConstruction();
    public Optional<Integer> getPrefetchDistance();

    public static class Builder {
        public Builder();
        public Builder setMaxLevel(short maxLevel);
        public Builder setM(int m);
        public Builder setEfConstruction(int efConstruction);
        public Builder setPrefetchDistance(Integer prefetchDistance);
        public HnswBuildParams build();
    }
}

Import

import org.lance.index.vector.HnswBuildParams;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
maxLevel	short	No	7	Maximum number of levels in the HNSW graph hierarchy
m	int	No	20	Number of edges per node in the graph (connectivity)
efConstruction	int	No	150	Number of nodes to examine during graph construction (higher = better quality, slower build)
prefetchDistance	Integer	No	2	Number of vectors ahead to prefetch while building the graph; null to disable

Accessor Outputs

Method	Return Type	Description
getMaxLevel()	short	Maximum graph levels
getM()	int	Edges per node
getEfConstruction()	int	Construction exploration factor
getPrefetchDistance()	Optional<Integer>	Prefetch distance, if set

Usage Examples

import org.lance.index.vector.HnswBuildParams;
import org.lance.index.vector.IvfBuildParams;
import org.lance.index.vector.SQBuildParams;
import org.lance.index.vector.VectorIndexParams;
import org.lance.index.DistanceType;

// Create HNSW params with defaults
HnswBuildParams defaultHnsw = new HnswBuildParams.Builder().build();

// Create HNSW params with custom settings
HnswBuildParams customHnsw = new HnswBuildParams.Builder()
    .setMaxLevel(10)
    .setM(32)
    .setEfConstruction(200)
    .setPrefetchDistance(4)
    .build();

// Use with IVF+HNSW+SQ vector index
IvfBuildParams ivf = new IvfBuildParams.Builder()
    .setNumPartitions(128)
    .build();
SQBuildParams sq = new SQBuildParams.Builder().build();

VectorIndexParams vectorParams = VectorIndexParams.withIvfHnswSqParams(
    DistanceType.L2, ivf, customHnsw, sq
);

Related Pages

• VectorIndexParams - Consumes HnswBuildParams for IVF+HNSW index variants
• IvfBuildParams - IVF partitioning parameters used alongside HNSW
• PQBuildParams - Product quantization params combinable with HNSW
• SQBuildParams - Scalar quantization params combinable with HNSW