Implementation:Lance format Lance Java WriteFragmentBuilder

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

Overview

Description

WriteFragmentBuilder provides a fluent builder API for writing data fragments to a Lance dataset. It supports two mutually exclusive data sources: VectorSchemaRoot (which requires a BufferAllocator) and ArrowArrayStream. The builder offers both a direct WriteParams object and individual parameter methods (maxRowsPerFile, maxRowsPerGroup, maxBytesPerFile, write mode, stable row IDs, data storage version, storage options). The execute() method writes the data and returns a list of FragmentMetadata for the created fragments.

Usage

Instances are created via Fragment.write() (package-private constructor). The builder validates that exactly one data source is set, that a dataset URI is provided, that an allocator is present when using VectorSchemaRoot, and that direct WriteParams and individual parameter methods are not mixed. An optional StorageOptionsProvider can be set for dynamic credential refresh during long-running write operations.

Code Reference

Source Location

java/src/main/java/org/lance/WriteFragmentBuilder.java

Signature

public class WriteFragmentBuilder {
    public WriteFragmentBuilder datasetUri(String datasetUri);
    public WriteFragmentBuilder allocator(BufferAllocator allocator);
    public WriteFragmentBuilder data(VectorSchemaRoot root);
    public WriteFragmentBuilder data(ArrowArrayStream stream);
    public WriteFragmentBuilder writeParams(WriteParams params);
    public WriteFragmentBuilder storageOptions(Map<String, String> storageOptions);
    public WriteFragmentBuilder storageOptionsProvider(StorageOptionsProvider provider);
    public WriteFragmentBuilder maxRowsPerFile(int maxRowsPerFile);
    public WriteFragmentBuilder maxRowsPerGroup(int maxRowsPerGroup);
    public WriteFragmentBuilder maxBytesPerFile(long maxBytesPerFile);
    public WriteFragmentBuilder mode(WriteParams.WriteMode mode);
    public WriteFragmentBuilder enableStableRowIds(boolean enable);
    public WriteFragmentBuilder dataStorageVersion(WriteParams.LanceFileVersion version);
    public List<FragmentMetadata> execute();
}

Import

import org.lance.WriteFragmentBuilder;

I/O Contract

Builder Methods

Method	Parameter Type	Required	Description
datasetUri()	String	Yes	URI where fragments will be written
allocator()	BufferAllocator	When using VectorSchemaRoot	Arrow buffer allocator
data(VectorSchemaRoot)	VectorSchemaRoot	One data source required	Data to write from a schema root
data(ArrowArrayStream)	ArrowArrayStream	One data source required	Data to write from a stream
writeParams()	WriteParams	No	Full write configuration; mutually exclusive with individual params
storageOptions()	Map<String, String>	No	Storage connection parameters
storageOptionsProvider()	StorageOptionsProvider	No	Dynamic credential refresh provider
maxRowsPerFile()	int	No	Maximum rows per output file
maxRowsPerGroup()	int	No	Maximum rows per row group
maxBytesPerFile()	long	No	Maximum bytes per output file
mode()	WriteParams.WriteMode	No	Write mode (CREATE, APPEND, OVERWRITE)
enableStableRowIds()	boolean	No	Enable or disable stable row IDs
dataStorageVersion()	WriteParams.LanceFileVersion	No	Target Lance file format version

Return Values

Method	Return Type	Description
execute()	List<FragmentMetadata>	Returns metadata for each fragment created during the write

Exceptions

Exception	Condition
IllegalStateException	Both VectorSchemaRoot and ArrowArrayStream are set
IllegalStateException	Neither VectorSchemaRoot nor ArrowArrayStream is set
IllegalStateException	VectorSchemaRoot is set but allocator is missing
IllegalStateException	Both writeParams() and individual parameter methods are used
NullPointerException	datasetUri is null

Usage Examples

import org.lance.Fragment;
import org.lance.FragmentMetadata;
import org.lance.WriteParams;
import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.VectorSchemaRoot;
import java.util.List;
import java.util.Map;

// Write fragments with individual parameters
List<FragmentMetadata> fragments = Fragment.write()
    .datasetUri("s3://bucket/dataset.lance")
    .allocator(new RootAllocator())
    .data(vectorSchemaRoot)
    .maxRowsPerFile(100000)
    .maxRowsPerGroup(1024)
    .storageOptions(Map.of("region", "us-east-1"))
    .execute();

// Write fragments with a WriteParams object
WriteParams params = new WriteParams.Builder()
    .withMode(WriteParams.WriteMode.APPEND)
    .withMaxRowsPerFile(50000)
    .withDataStorageVersion(WriteParams.LanceFileVersion.V2_1)
    .build();

List<FragmentMetadata> fragments = Fragment.write()
    .datasetUri("/local/dataset.lance")
    .allocator(allocator)
    .data(root)
    .writeParams(params)
    .execute();

// Write from an ArrowArrayStream (no allocator needed)
List<FragmentMetadata> fragments = Fragment.write()
    .datasetUri("s3://bucket/dataset.lance")
    .data(arrowArrayStream)
    .execute();

Related Pages

• Lance_format_Lance_Java_WriteParams - Write parameters that configure the fragment write behavior
• Lance_format_Lance_Java_FragmentMetadata - Metadata returned for each written fragment
• Lance_format_Lance_Java_FragmentOperation - Deprecated API for committing fragments (use Transaction instead)
• Lance_format_Lance_Java_Transaction - Modern API for committing written fragments to a dataset