Implementation:Lance format Lance Java FragmentOperation

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

Overview

Description

⚠️ DEPRECATED: This entire class is deprecated. Use Transaction instead. See Lance_format_Lance_Warning_Deprecated_Java_APIs.

FragmentOperation is a deprecated abstract class that provides fragment-level commit operations for Lance datasets. It defines two concrete inner classes: Append (for appending new fragments to an existing dataset) and Overwrite (for replacing all fragments with a new schema). Both operations commit their changes to a dataset at a specified path and return a new Dataset instance. This class has been superseded by the Transaction API, which offers a more flexible and extensible approach to dataset modifications.

Usage

Although deprecated, FragmentOperation is still present in the codebase. New code should use Transaction instead. The Append subclass takes a list of FragmentMetadata and commits them as new fragments. The Overwrite subclass additionally requires an Arrow Schema to define the new dataset schema. Both validate their inputs using Preconditions checks.

Code Reference

Source Location

java/src/main/java/org/lance/FragmentOperation.java

Signature

@Deprecated
public abstract class FragmentOperation {
    public abstract Dataset commit(BufferAllocator allocator, String path,
                                   Optional<Long> readVersion,
                                   Map<String, String> storageOptions);

    public static class Append extends FragmentOperation {
        public Append(List<FragmentMetadata> fragments);
        public Dataset commit(BufferAllocator allocator, String path,
                              Optional<Long> readVersion,
                              Map<String, String> storageOptions);
    }

    public static class Overwrite extends FragmentOperation {
        public Overwrite(List<FragmentMetadata> fragments, Schema schema);
        public Dataset commit(BufferAllocator allocator, String path,
                              Optional<Long> readVersion,
                              Map<String, String> storageOptions);
    }
}

Import

import org.lance.FragmentOperation;

I/O Contract

Append Constructor Parameters

Name	Type	Description
fragments	List<FragmentMetadata>	Non-null, non-empty list of fragment metadata to append

Overwrite Constructor Parameters

Name	Type	Description
fragments	List<FragmentMetadata>	Non-null, non-empty list of fragment metadata for the new dataset
schema	Schema	Apache Arrow schema for the overwritten dataset

commit() Parameters

Name	Type	Description
allocator	BufferAllocator	Arrow buffer allocator (must not be null)
path	String	Dataset URI or filesystem path (must not be null)
readVersion	Optional<Long>	Expected current version for optimistic concurrency (must not be null)
storageOptions	Map<String, String>	Storage connection parameters (credentials, endpoint, etc.)

Return Values

Method	Return Type	Description
commit()	Dataset	Returns a new Dataset instance reflecting the committed changes

Usage Examples

import org.lance.FragmentOperation;
import org.lance.FragmentMetadata;
import org.lance.Dataset;
import org.apache.arrow.memory.RootAllocator;
import java.util.Optional;
import java.util.HashMap;

// NOTE: This API is deprecated. Use Transaction instead.

// Append fragments to an existing dataset
List<FragmentMetadata> newFragments = Fragment.write()
    .datasetUri("s3://bucket/dataset.lance")
    .allocator(allocator)
    .data(root)
    .execute();

FragmentOperation.Append append = new FragmentOperation.Append(newFragments);
Dataset updatedDataset = append.commit(
    allocator,
    "s3://bucket/dataset.lance",
    Optional.of(currentVersion),
    new HashMap<>()
);

// Overwrite dataset with new schema and fragments
FragmentOperation.Overwrite overwrite = new FragmentOperation.Overwrite(newFragments, schema);
Dataset replacedDataset = overwrite.commit(
    allocator,
    "s3://bucket/dataset.lance",
    Optional.of(currentVersion),
    new HashMap<>()
);

Related Pages

• Lance_format_Lance_Java_Transaction - The recommended replacement for FragmentOperation
• Lance_format_Lance_Java_FragmentMetadata - Fragment metadata consumed by both Append and Overwrite operations
• Lance_format_Lance_Java_WriteFragmentBuilder - Builder for creating fragments that produce FragmentMetadata
• Heuristic:Lance_format_Lance_Warning_Deprecated_Java_APIs