Implementation:Lance format Lance Java UpdateOp

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

Overview

Description

The Update class is an immutable operation that modifies specific rows or columns within a Lance dataset. It implements the Operation interface and is the most complex operation type, supporting two distinct update modes via the UpdateMode enum: RewriteRows and RewriteColumns.

The operation tracks six components: fragment IDs that were removed, fragments with updated metadata, newly created fragments, an array of modified field IDs, an array of field IDs for preserving fragment deletion bitmaps, and the optional update mode. All collections default to empty values.

Usage

Use Update to modify existing data in a Lance dataset. RewriteRows mode is used when updating specific rows (similar to SQL UPDATE with a WHERE clause). RewriteColumns mode is used when replacing entire columns with new values. The operation handles the bookkeeping of tracking which fragments are removed, updated, or newly created.

Code Reference

Source Location

java/src/main/java/org/lance/operation/Update.java

Signature

public class Update implements Operation {
    public static Builder builder();
    public List<Long> removedFragmentIds();
    public List<FragmentMetadata> updatedFragments();
    public List<FragmentMetadata> newFragments();
    public long[] fieldsModified();
    public long[] fieldsForPreservingFragBitmap();
    public Optional<UpdateMode> updateMode();
    public String name();  // returns "Update"

    public enum UpdateMode {
        RewriteRows,
        RewriteColumns;
    }
}

Import

import org.lance.operation.Update;
import org.lance.operation.Update.UpdateMode;

I/O Contract

Inputs

Parameter	Type	Required	Description
removedFragmentIds	List<Long>	No	IDs of fragments fully removed by the update (defaults to empty)
updatedFragments	List<FragmentMetadata>	No	Fragments with updated metadata (defaults to empty)
newFragments	List<FragmentMetadata>	No	Newly created fragments (defaults to empty)
fieldsModified	long[]	No	Array of field IDs that were modified (defaults to empty array)
fieldsForPreservingFragBitmap	long[]	No	Field IDs for preserving fragment deletion bitmaps (defaults to empty array)
updateMode	Optional<UpdateMode>	No	The update mode: RewriteRows or RewriteColumns (defaults to empty)

Outputs

Return	Type	Description
removedFragmentIds()	List<Long>	Fragment IDs that were removed
updatedFragments()	List<FragmentMetadata>	Fragments with updated metadata
newFragments()	List<FragmentMetadata>	Newly created fragments
fieldsModified()	long[]	Modified field IDs
fieldsForPreservingFragBitmap()	long[]	Field IDs for bitmap preservation
updateMode()	Optional<UpdateMode>	The update mode
name()	String	Returns "Update" for JNI dispatch

Usage Examples

// Update specific rows in the dataset
Update updateOp = Update.builder()
    .removedFragmentIds(List.of(3L))
    .updatedFragments(updatedFrags)
    .newFragments(newFrags)
    .fieldsModified(new long[]{1L, 2L})
    .updateMode(Optional.of(UpdateMode.RewriteRows))
    .build();

String opName = updateOp.name(); // "Update"
Optional<UpdateMode> mode = updateOp.updateMode(); // Optional[RewriteRows]

Related Pages

• Implementation:Lance_format_Lance_Java_DeleteOp -- Removes rows entirely rather than updating them
• Implementation:Lance_format_Lance_Java_DataReplacementOp -- Replaces column data at the file level
• Implementation:Lance_format_Lance_Java_MergeOp -- Adds new columns via schema evolution