Implementation:Lance format Lance Java SQBuildParams

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

Overview

Description

SQBuildParams is a Java class in the org.lance.index.vector package that defines parameters for using Scalar Quantization (SQ) to compress vectors in a Lance index. SQ maps floating-point vector components to lower-bit integer representations by learning a scaling range from training data. The class is immutable and uses a Builder pattern with two configurable parameters: the number of quantization bits and the training sample rate.

Usage

SQBuildParams is used as an optional component of VectorIndexParams when creating IVF_SQ or IVF_HNSW_SQ index types. SQ and PQ parameters are mutually exclusive -- only one quantizer can be used per index. SQ is simpler than PQ and generally offers a good trade-off between compression ratio and search accuracy.

Code Reference

Source Location

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

Signature

public class SQBuildParams {
    public short getNumBits();
    public int getSampleRate();

    public static class Builder {
        public Builder();
        public Builder setNumBits(short numBits);
        public Builder setSampleRate(int sampleRate);
        public SQBuildParams build();
    }
}

Import

import org.lance.index.vector.SQBuildParams;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
numBits	short	No	8	Number of bits for the scaling range quantization
sampleRate	int	No	256	Sample rate for training the SQ model

Accessor Outputs

Method	Return Type	Description
getNumBits()	short	Number of quantization bits
getSampleRate()	int	Training sample rate

Usage Examples

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

// Create SQ params with defaults (8 bits, sample rate 256)
SQBuildParams defaultSq = new SQBuildParams.Builder().build();

// Create SQ params with custom settings
SQBuildParams customSq = new SQBuildParams.Builder()
    .setNumBits((short) 4)
    .setSampleRate(512)
    .build();

// Use with IVF+HNSW+SQ vector index
IvfBuildParams ivf = new IvfBuildParams.Builder()
    .setNumPartitions(128)
    .build();
HnswBuildParams hnsw = new HnswBuildParams.Builder()
    .setM(32)
    .setEfConstruction(200)
    .build();

VectorIndexParams vectorParams = VectorIndexParams.withIvfHnswSqParams(
    DistanceType.L2, ivf, hnsw, defaultSq
);

Related Pages

• VectorIndexParams - Consumes SQBuildParams for IVF_SQ and IVF_HNSW_SQ indices
• PQBuildParams - Alternative quantizer (mutually exclusive with SQ)
• IvfBuildParams - IVF partitioning used alongside SQ
• HnswBuildParams - HNSW graph combinable with SQ