Implementation:Lance format Lance Java IndexOptions

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

Overview

Description

IndexOptions is a Java class in the org.lance.index package that encapsulates all options for building indices on a Lance dataset. It uses an immutable design with a Builder pattern that requires three mandatory parameters: the column names to index, the IndexType, and the IndexParams. Additional optional settings control whether to replace existing indices, whether to train the index, which fragment IDs to target (for distributed indexing), a shared UUID for fragment-level indices, a custom index name, and optional preprocessed data via an Arrow ArrowArrayStream.

Usage

IndexOptions is constructed via IndexOptions.builder(columns, indexType, indexParams) and then passed to dataset index-creation APIs. The builder enforces that the three required parameters are non-null using Guava Preconditions.

Code Reference

Source Location

java/src/main/java/org/lance/index/IndexOptions.java

Signature

public class IndexOptions {
    public static Builder builder(
        List<String> columns, IndexType indexType, IndexParams indexParams);

    public Optional<String> getIndexUUID();
    public Optional<List<Integer>> getFragmentIds();
    public boolean isReplace();
    public boolean isTrain();
    public Optional<String> getIndexName();
    public IndexParams getIndexParams();
    public IndexType getIndexType();
    public List<String> getColumns();
    public Optional<ArrowArrayStream> getPreprocessedData();

    public static class Builder { ... }
}

Import

import org.lance.index.IndexOptions;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
columns	List<String>	Yes	N/A	Column names to build the index on
indexType	IndexType	Yes	N/A	The type of index to create
indexParams	IndexParams	Yes	N/A	Index-specific parameters (vector or scalar)
replace	boolean	No	false	Replace existing index if it exists
train	boolean	No	true	Train the index on the data; if false, creates empty index
fragmentIds	List<Integer>	No	null	Restrict index to specific fragments (distributed indexing)
indexUUID	String	No	null	Shared UUID for fragment-level distributed indexing
indexName	String	No	null	Custom index name; auto-generated if not provided
preprocessedData	ArrowArrayStream	No	null	Preprocessed data to avoid recomputation

Accessor Outputs

Method	Return Type	Description
getColumns()	List<String>	Column names for the index
getIndexType()	IndexType	The index type
getIndexParams()	IndexParams	Index-specific parameters
isReplace()	boolean	Whether to replace an existing index
isTrain()	boolean	Whether to train the index
getFragmentIds()	Optional<List<Integer>>	Optional fragment IDs
getIndexUUID()	Optional<String>	Optional shared UUID
getIndexName()	Optional<String>	Optional custom index name
getPreprocessedData()	Optional<ArrowArrayStream>	Optional preprocessed Arrow data

Usage Examples

import org.lance.index.IndexOptions;
import org.lance.index.IndexType;
import org.lance.index.IndexParams;
import org.lance.index.vector.VectorIndexParams;
import org.lance.index.DistanceType;
import java.util.Arrays;

// Create vector index parameters
VectorIndexParams vectorParams = VectorIndexParams.ivfPq(
    256, 8, 16, DistanceType.L2, 50
);
IndexParams params = IndexParams.builder()
    .setVectorIndexParams(vectorParams)
    .build();

// Build index options for a vector column
IndexOptions options = IndexOptions.builder(
        Arrays.asList("embedding"), IndexType.IVF_PQ, params)
    .replace(true)
    .withIndexName("embedding_ivf_pq_idx")
    .build();

// Use with dataset API
// dataset.createIndex(options);

Related Pages

• IndexParams - Container for vector or scalar index parameters
• IndexType - Enum of supported index types
• VectorIndexParams - Vector-specific index parameters
• ScalarIndexParams - Scalar-specific index parameters