Implementation:Lance format Lance Java PQBuildParams

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

Overview

Description

PQBuildParams is a Java class in the org.lance.index.vector package that defines parameters for training a PQ (Product Quantization) model for vector compression. PQ works by dividing each vector into subvectors and running k-means clustering on each subvector independently to build a codebook. This quantization reduces memory usage and speeds up distance computations during search. The class is immutable and uses a Builder pattern with sensible defaults. It also supports providing pre-trained codebooks for distributed workflows.

Usage

PQBuildParams is used as an optional component of VectorIndexParams when creating IVF_PQ or IVF_HNSW_PQ index types. PQ and SQ parameters are mutually exclusive -- only one quantizer can be used per index. For distributed builds, pre-trained codebooks can be set via setCodebook(), typically obtained from VectorTrainer.trainPqCodebook().

Code Reference

Source Location

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

Signature

public class PQBuildParams {
    public int getNumSubVectors();
    public int getNumBits();
    public int getMaxIters();
    public int getKmeansRedos();
    public int getSampleRate();
    public float[] getCodebook();

    public static class Builder {
        public Builder();
        public Builder setNumSubVectors(int numSubVectors);
        public Builder setNumBits(int numBits);
        public Builder setMaxIters(int maxIters);
        public Builder setKmeansRedos(int kmeansRedos);
        public Builder setSampleRate(int sampleRate);
        public Builder setCodebook(float[] codebook);
        public PQBuildParams build();
    }
}

Import

import org.lance.index.vector.PQBuildParams;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
numSubVectors	int	No	16	Number of subvectors to divide source vectors into; must be a divisor of vector dimension
numBits	int	No	8	Number of bits to represent one PQ centroid (currently only 8 is supported)
maxIters	int	No	50	Maximum iterations for k-means clustering per subvector
kmeansRedos	int	No	1	Number of k-means runs; best result is kept
sampleRate	int	No	256	Sample rate for training PQ codebook from dataset
codebook	float[]	No	null	Pre-trained PQ codebook flattened as [num_centroids][dimension]

Accessor Outputs

Method	Return Type	Description
getNumSubVectors()	int	Number of subvectors
getNumBits()	int	Bits per PQ centroid
getMaxIters()	int	Max k-means iterations
getKmeansRedos()	int	K-means redo count
getSampleRate()	int	Training sample rate
getCodebook()	float[]	Pre-trained codebook (null if not set)

Usage Examples

import org.lance.index.vector.PQBuildParams;
import org.lance.index.vector.IvfBuildParams;
import org.lance.index.vector.VectorIndexParams;
import org.lance.index.DistanceType;

// Create PQ params with defaults (16 subvectors, 8 bits)
PQBuildParams defaultPq = new PQBuildParams.Builder().build();

// Create PQ params with custom settings
PQBuildParams customPq = new PQBuildParams.Builder()
    .setNumSubVectors(32)
    .setNumBits(8)
    .setMaxIters(100)
    .setKmeansRedos(3)
    .setSampleRate(512)
    .build();

// Use pre-trained codebook
float[] codebook = VectorTrainer.trainPqCodebook(dataset, "embedding", customPq);
PQBuildParams withCodebook = new PQBuildParams.Builder()
    .setNumSubVectors(32)
    .setCodebook(codebook)
    .build();

// Use with IVF+PQ index
IvfBuildParams ivf = new IvfBuildParams.Builder()
    .setNumPartitions(128)
    .build();
VectorIndexParams vectorParams = VectorIndexParams.withIvfPqParams(
    DistanceType.Cosine, ivf, customPq
);

// Convenience factory method
VectorIndexParams quickPq = VectorIndexParams.ivfPq(
    128, 8, 16, DistanceType.L2, 50
);

Related Pages

• VectorIndexParams - Consumes PQBuildParams for IVF_PQ and IVF_HNSW_PQ indices
• VectorTrainer - Can pre-train PQ codebooks for distributed builds
• IvfBuildParams - IVF partitioning used alongside PQ
• SQBuildParams - Alternative quantizer (mutually exclusive with PQ)
• HnswBuildParams - HNSW graph combinable with PQ