Implementation:Lance format Lance Java BasePath

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

Overview

Description

BasePath is a final immutable value class in the Lance Java SDK that represents a base path entry used in dataset storage configuration. Each BasePath encapsulates an identifier, an optional human-readable name, a filesystem or object store path string, and a flag indicating whether the path serves as the dataset root. BasePath instances are primarily used within WriteParams to configure initial base paths and storage layout for write operations.

Usage

BasePath objects are constructed directly via the public constructor and are typically collected into lists for use with WriteParams.Builder.withInitialBases(). Since the class is final and all fields are set in the constructor, BasePath instances are inherently thread-safe.

Code Reference

Source Location

java/src/main/java/org/lance/BasePath.java

Signature

public final class BasePath {
    public BasePath(int id, Optional<String> name, String path, boolean isDatasetRoot);
    public int getId();
    public Optional<String> getName();
    public String getPath();
    public boolean isDatasetRoot();
    public String toString();
}

Import

import org.lance.BasePath;

I/O Contract

Constructor Parameters

Name	Type	Description
id	int	Unique numeric identifier for the base path entry
name	Optional<String>	Optional human-readable name for the base path
path	String	The filesystem or object store path string
isDatasetRoot	boolean	Whether this path represents the root of the dataset

Return Values

Method	Return Type	Description
getId()	int	Returns the numeric identifier
getName()	Optional<String>	Returns the optional name
getPath()	String	Returns the path string
isDatasetRoot()	boolean	Returns true if this is the dataset root path
toString()	String	Returns a Guava MoreObjects string representation

Usage Examples

import org.lance.BasePath;
import java.util.Optional;
import java.util.List;
import java.util.Arrays;

// Create a base path representing the dataset root
BasePath rootPath = new BasePath(0, Optional.of("primary"), "s3://bucket/dataset", true);

// Create a secondary base path without a name
BasePath secondaryPath = new BasePath(1, Optional.empty(), "s3://bucket/archive", false);

// Use base paths in write parameters
List<BasePath> bases = Arrays.asList(rootPath, secondaryPath);
WriteParams params = new WriteParams.Builder()
    .withInitialBases(bases)
    .build();

// Inspect a base path
System.out.println(rootPath.getId());          // 0
System.out.println(rootPath.getPath());        // s3://bucket/dataset
System.out.println(rootPath.isDatasetRoot());  // true

Related Pages

• Lance_format_Lance_Java_WriteParams - Uses BasePath lists for configuring initial base paths during write operations
• Lance_format_Lance_Java_WriteFragmentBuilder - Fragment writer that accepts WriteParams containing BasePath configuration