Implementation:Lance format Lance Java DatasetDeltaBuilder

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

Overview

Description

DatasetDeltaBuilder is a builder class for constructing DatasetDelta instances that explore changes between two versions of a Lance dataset. It supports two mutually exclusive modes of version comparison: comparedAgainstVersion (which compares the current dataset version against a specified version, automatically ordering them) and explicit beginVersion/endVersion specification (where beginVersion is exclusive and endVersion is inclusive). The builder delegates to a native JNI method for actual delta computation.

Usage

The builder is constructed with a Dataset reference. Callers choose one of two comparison modes, then call build() to create the DatasetDelta. Validation of the mutually exclusive modes is performed on the Rust side during the native build call. The native library is loaded via JniLoader.ensureLoaded() in the static initializer.

Code Reference

Source Location

java/src/main/java/org/lance/delta/DatasetDeltaBuilder.java

Signature

public class DatasetDeltaBuilder {
    public DatasetDeltaBuilder(Dataset dataset);
    public DatasetDeltaBuilder comparedAgainstVersion(long version);
    public DatasetDeltaBuilder withBeginVersion(long version);
    public DatasetDeltaBuilder withEndVersion(long version);
    public DatasetDelta build();
}

Import

import org.lance.delta.DatasetDeltaBuilder;

I/O Contract

Constructor Parameters

Name	Type	Description
dataset	Dataset	The dataset to compute deltas against

Builder Methods

Method	Type	Description
comparedAgainstVersion()	long	Compare current dataset version against this version; auto-orders begin/end. Mutually exclusive with explicit begin/end.
withBeginVersion()	long	Set the beginning version (exclusive). Must be used with withEndVersion(). Mutually exclusive with comparedAgainstVersion().
withEndVersion()	long	Set the ending version (inclusive). Must be used with withBeginVersion(). Mutually exclusive with comparedAgainstVersion().

Return Values

Method	Return Type	Description
build()	DatasetDelta	Creates and returns a DatasetDelta for exploring changes between the specified versions

Usage Examples

import org.lance.delta.DatasetDeltaBuilder;
import org.lance.delta.DatasetDelta;
import org.lance.Dataset;

Dataset dataset = Dataset.open().uri("/data/my_dataset.lance").build();

// Mode 1: Compare current version against a previous version
// The builder automatically determines which is begin and which is end
try (DatasetDelta delta = new DatasetDeltaBuilder(dataset)
        .comparedAgainstVersion(3)
        .build()) {
    // Explore changes...
    System.out.println("Transactions: " + delta.listTransactions().size());
}

// Mode 2: Explicit version range (beginVersion exclusive, endVersion inclusive)
try (DatasetDelta delta = new DatasetDeltaBuilder(dataset)
        .withBeginVersion(2)
        .withEndVersion(7)
        .build()) {
    // Explores transactions for versions 3, 4, 5, 6, 7
    System.out.println("Transactions: " + delta.listTransactions().size());
}

Related Pages

• Lance_format_Lance_Java_DatasetDelta - The DatasetDelta object produced by this builder
• Lance_format_Lance_Java_Transaction - Transactions that appear in the delta's transaction list
• Lance_format_Lance_Java_JniLoader - Loads the native library used by DatasetDeltaBuilder