Implementation:Lance format Lance Java DatasetDelta

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

Overview

Description

DatasetDelta is a closeable class that provides a view of differences between two versions of a Lance dataset. It wraps a native Rust DatasetDelta handle via JNI and offers methods to list the transactions that occurred between versions, as well as streaming access to inserted and updated rows via Apache Arrow ArrowReader instances. The class uses a LockManager for thread-safe access to the native handle and ensures proper cleanup of native resources on close.

Usage

DatasetDelta instances are created by DatasetDeltaBuilder. Once obtained, callers can use listTransactions() to inspect what changes occurred, or getInsertedRows() and getUpdatedRows() to stream the actual data changes. The class implements Closeable and should be used within a try-with-resources block to ensure the native handle is released. All public methods validate that the native handle is still valid before proceeding.

Code Reference

Source Location

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

Signature

public class DatasetDelta implements Closeable {
    public List<Transaction> listTransactions();
    public ArrowReader getInsertedRows() throws IOException;
    public ArrowReader getUpdatedRows() throws IOException;
    public void close();
}

Import

import org.lance.delta.DatasetDelta;

I/O Contract

**Methods**
Method	Return Type	Description
listTransactions()	`List<Transaction>`	Returns a list of transactions between begin_version+1 and end_version (inclusive)
getInsertedRows()	`ArrowReader`	Returns a streaming ArrowReader for rows inserted between the two versions
getUpdatedRows()	`ArrowReader`	Returns a streaming ArrowReader for rows updated between the two versions
close()	`void`	Releases the native Rust DatasetDelta handle

**Exceptions**
Method	Exception	Condition
listTransactions()	`IllegalArgumentException`	The DatasetDelta has been closed (nativeDeltaHandle is 0)
getInsertedRows()	`IllegalArgumentException`	The DatasetDelta has been closed
getInsertedRows()	`IOException`	Native streaming operation fails
getUpdatedRows()	`IllegalArgumentException`	The DatasetDelta has been closed
getUpdatedRows()	`IOException`	Native streaming operation fails

**Thread Safety**
Aspect	Description
Read operations	Protected by LockManager read locks; multiple concurrent reads are safe
Close operation	Protected by LockManager write lock; ensures exclusive access during cleanup
Post-close access	All methods check nativeDeltaHandle != 0 and throw if closed

Usage Examples

import org.lance.delta.DatasetDelta;
import org.lance.delta.DatasetDeltaBuilder;
import org.lance.Dataset;
import org.lance.Transaction;
import org.apache.arrow.vector.ipc.ArrowReader;
import java.util.List;

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

// View changes between version 5 and the current version
try (DatasetDelta delta = new DatasetDeltaBuilder(dataset)
        .comparedAgainstVersion(5)
        .build()) {

    // List all transactions in the range
    List<Transaction> transactions = delta.listTransactions();
    for (Transaction txn : transactions) {
        System.out.println("Transaction: " + txn.uuid());
        System.out.println("  Operation: " + txn.operation());
    }

    // Stream inserted rows
    try (ArrowReader insertedReader = delta.getInsertedRows()) {
        while (insertedReader.loadNextBatch()) {
            System.out.println("Inserted batch: "
                + insertedReader.getVectorSchemaRoot().getRowCount() + " rows");
        }
    }

    // Stream updated rows
    try (ArrowReader updatedReader = delta.getUpdatedRows()) {
        while (updatedReader.loadNextBatch()) {
            System.out.println("Updated batch: "
                + updatedReader.getVectorSchemaRoot().getRowCount() + " rows");
        }
    }
}

Related Pages

Lance_format_Lance_Java_DatasetDeltaBuilder - Builder that creates DatasetDelta instances
Lance_format_Lance_Java_Transaction - Transaction objects returned by listTransactions()
Lance_format_Lance_Java_JniLoader - Loads the native library used by DatasetDelta

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment