Implementation:Lance format Lance Java Transaction

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

Overview

Description

Transaction is the primary mechanism for committing changes to a Lance dataset in the Java SDK, aligned with the Rust Transaction struct. A Transaction encapsulates a read version (for optimistic concurrency control), a UUID for unique identification, an Operation describing the change, optional write parameters, and optional transaction properties. Committing a transaction does not mutate the original dataset; instead, it returns a new Dataset instance reflecting the committed state.

Usage

Transactions are constructed via the inner Transaction.Builder class, which requires a Dataset reference and automatically generates a UUID. The builder enforces that exactly one Operation is set (attempting to set a second throws IllegalStateException). After building, call commit() to apply the transaction. The release() method should be called to free native resources held by the Operation when the transaction is no longer needed.

Code Reference

Source Location

java/src/main/java/org/lance/Transaction.java

Signature

public class Transaction {
    public long readVersion();
    public String uuid();
    public Operation operation();
    public Map<String, String> writeParams();
    public Optional<Map<String, String>> transactionProperties();
    public Dataset commit();
    public void release();
    public String toString();
    public boolean equals(Object o);

    public static class Builder {
        public Builder(Dataset dataset);
        public Builder readVersion(long readVersion);
        public Builder transactionProperties(Map<String, String> properties);
        public Builder writeParams(Map<String, String> writeParams);
        public Builder operation(Operation operation);
        public Transaction build();
    }
}

Import

import org.lance.Transaction;

I/O Contract

**Builder Methods**
Method	Type	Description
Builder(Dataset)	`Dataset`	Target dataset; a UUID is auto-generated
readVersion()	`long`	Version the transaction was read from (for conflict detection)
operation()	`Operation`	The dataset mutation operation (append, overwrite, etc.); exactly one required
writeParams()	`Map<String, String>`	Optional write parameters
transactionProperties()	`Map<String, String>`	Optional metadata properties for the transaction

**Transaction Methods**
Method	Return Type	Description
readVersion()	`long`	Returns the read version for optimistic concurrency
uuid()	`String`	Returns the unique transaction identifier
operation()	`Operation`	Returns the dataset operation
writeParams()	`Map<String, String>`	Returns the write parameters (empty map if null)
transactionProperties()	`Optional<Map<String, String>>`	Returns optional transaction properties
commit()	`Dataset`	Commits the transaction and returns a new Dataset
release()	`void`	Releases native resources held by the operation

**Exceptions**
Method	Exception	Condition
Builder.operation()	`IllegalStateException`	An operation has already been set on this builder
Builder.build()	`IllegalStateException`	No operation has been set
commit()	`UnsupportedOperationException`	The transaction has no associated dataset (creation not yet supported)

Usage Examples

import org.lance.Transaction;
import org.lance.Dataset;
import org.lance.operation.Operation;

// Build and commit a transaction
Dataset dataset = Dataset.open().uri("/data/my_dataset.lance").build();

Transaction txn = new Transaction.Builder(dataset)
    .readVersion(dataset.version())
    .operation(myAppendOperation)
    .writeParams(Map.of("key", "value"))
    .transactionProperties(Map.of("source", "etl-pipeline"))
    .build();

// Commit returns a new dataset; the original is unchanged
Dataset newDataset = txn.commit();

// Release native resources when done
txn.release();

// Inspect transaction metadata
System.out.println("UUID: " + txn.uuid());
System.out.println("Read version: " + txn.readVersion());
System.out.println("Operation: " + txn.operation());

Related Pages

Lance_format_Lance_Java_FragmentOperation - The deprecated predecessor to Transaction
Lance_format_Lance_Java_FragmentMetadata - Fragment metadata that Operations reference
Lance_format_Lance_Java_DatasetDelta - Returns Transaction lists when listing changes between versions
Lance_format_Lance_Java_WriteParams - Write parameters that can be passed to a transaction

Page Connections

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

Principle

Implementation

Heuristic

Environment