Implementation:Lance format Lance Java WriteParams

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

Overview

Description

WriteParams is an immutable configuration class for Lance write operations. It encapsulates parameters controlling file layout (max rows per file, max rows per group, max bytes per file), write mode (CREATE, APPEND, OVERWRITE), stable row ID generation, Lance file format version selection, V2 manifest paths, storage connection options, and base path configuration (initial bases and target bases). All fields are Optional to avoid conflicting with Rust-side defaults. The class also defines two inner enums: WriteMode and LanceFileVersion.

Usage

WriteParams is constructed via its inner Builder class and passed to WriteFragmentBuilder.writeParams() or used in dataset write operations. The LanceFileVersion enum maps Java constants to Rust version strings (e.g., V2_1 maps to "2.1"). The getMode() method returns the enum name as a String for JNI interop.

Code Reference

Source Location

java/src/main/java/org/lance/WriteParams.java

Signature

public class WriteParams {
    public enum WriteMode { CREATE, APPEND, OVERWRITE }

    public enum LanceFileVersion {
        LEGACY("legacy"), V0_1("0.1"), V2_0("2.0"),
        STABLE("stable"), V2_1("2.1"), NEXT("next"), V2_2("2.2");
        public String getVersionString();
    }

    public Optional<Integer> getMaxRowsPerFile();
    public Optional<Integer> getMaxRowsPerGroup();
    public Optional<Long> getMaxBytesPerFile();
    public Optional<String> getMode();
    public Optional<Boolean> getEnableStableRowIds();
    public Optional<String> getDataStorageVersion();
    public Optional<Boolean> getEnableV2ManifestPaths();
    public Map<String, String> getStorageOptions();
    public Optional<List<BasePath>> getInitialBases();
    public Optional<List<String>> getTargetBases();
    public String toString();

    public static class Builder {
        public Builder withMaxRowsPerFile(int maxRowsPerFile);
        public Builder withMaxRowsPerGroup(int maxRowsPerGroup);
        public Builder withMaxBytesPerFile(long maxBytesPerFile);
        public Builder withMode(WriteMode mode);
        public Builder withDataStorageVersion(LanceFileVersion dataStorageVersion);
        public Builder withStorageOptions(Map<String, String> storageOptions);
        public Builder withEnableStableRowIds(boolean enableStableRowIds);
        public Builder withEnableV2ManifestPaths(boolean enableV2ManifestPaths);
        public Builder withInitialBases(List<BasePath> initialBases);
        public Builder withTargetBases(List<String> targetBases);
        public WriteParams build();
    }
}

Import

import org.lance.WriteParams;

I/O Contract

Builder Parameters

Method	Type	Description
withMaxRowsPerFile()	int	Maximum number of rows per output file
withMaxRowsPerGroup()	int	Maximum number of rows per row group within a file
withMaxBytesPerFile()	long	Maximum file size in bytes
withMode()	WriteMode	Write mode: CREATE, APPEND, or OVERWRITE
withDataStorageVersion()	LanceFileVersion	Target Lance file format version
withStorageOptions()	Map<String, String>	Storage connection parameters
withEnableStableRowIds()	boolean	Enable stable row ID generation
withEnableV2ManifestPaths()	boolean	Enable V2 manifest path layout
withInitialBases()	List<BasePath>	Initial base path configuration for the dataset
withTargetBases()	List<String>	Target base path strings for writes

LanceFileVersion Values

Enum Constant	Version String	Description
LEGACY	"legacy"	Original Lance file format
V0_1	"0.1"	Version 0.1
V2_0	"2.0"	Version 2.0
STABLE	"stable"	Current stable version
V2_1	"2.1"	Version 2.1
NEXT	"next"	Next/preview version
V2_2	"2.2"	Version 2.2

Usage Examples

import org.lance.WriteParams;
import org.lance.BasePath;
import java.util.Arrays;
import java.util.Map;
import java.util.Optional;

// Basic write params with append mode
WriteParams params = new WriteParams.Builder()
    .withMode(WriteParams.WriteMode.APPEND)
    .withMaxRowsPerFile(100000)
    .withMaxRowsPerGroup(1024)
    .build();

// Full configuration with storage version and options
WriteParams params = new WriteParams.Builder()
    .withMode(WriteParams.WriteMode.CREATE)
    .withDataStorageVersion(WriteParams.LanceFileVersion.V2_1)
    .withMaxBytesPerFile(256L * 1024 * 1024)
    .withEnableStableRowIds(true)
    .withEnableV2ManifestPaths(true)
    .withStorageOptions(Map.of("region", "us-west-2"))
    .build();

// With base path configuration
BasePath root = new BasePath(0, Optional.of("primary"), "s3://main-bucket/data", true);
WriteParams params = new WriteParams.Builder()
    .withInitialBases(Arrays.asList(root))
    .withTargetBases(Arrays.asList("s3://main-bucket/data"))
    .build();

// Inspect params
System.out.println(params.getMode());                // Optional[APPEND]
System.out.println(params.getDataStorageVersion());   // Optional[2.1]

Related Pages

• Lance_format_Lance_Java_WriteFragmentBuilder - Consumes WriteParams for fragment write configuration
• Lance_format_Lance_Java_BasePath - Base path entries used in withInitialBases()
• Lance_format_Lance_Java_ReadOptions - Analogous configuration class for read operations
• Lance_format_Lance_Java_Transaction - Transactions that can include write parameters