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