Implementation:Lance format Lance Java ReadOptions

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

Overview

Description

ReadOptions is an immutable configuration class for controlling how a Lance dataset is opened and read. It encapsulates version selection, I/O block size hints, index and metadata cache sizing, storage connection parameters, serialized manifest data for IPC transfer, and an optional StorageOptionsProvider for automatic credential refresh. The class uses a Builder pattern with sensible defaults aligned with the Rust implementation: 6 GiB for index cache and 1 GiB for metadata cache.

Usage

ReadOptions is constructed exclusively through its inner Builder class. Instances are passed to OpenDatasetBuilder.readOptions() when opening a dataset. The Builder provides both current and deprecated methods for cache sizing (the deprecated methods convert entry counts to approximate byte sizes).

Code Reference

Source Location

java/src/main/java/org/lance/ReadOptions.java

Signature

public class ReadOptions {
    public Optional<Long> getVersion();
    public Optional<Integer> getBlockSize();
    public long getIndexCacheSizeBytes();
    public long getMetadataCacheSizeBytes();
    public Map<String, String> getStorageOptions();
    public Optional<ByteBuffer> getSerializedManifest();
    public Optional<StorageOptionsProvider> getStorageOptionsProvider();
    public String toString();

    public static class Builder {
        public Builder setVersion(long version);
        public Builder setBlockSize(int blockSize);
        public Builder setIndexCacheSizeBytes(long indexCacheSizeBytes);
        public Builder setMetadataCacheSizeBytes(long metadataCacheSizeBytes);
        @Deprecated public Builder setIndexCacheSize(int indexCacheSize);
        @Deprecated public Builder setMetadataCacheSize(int metadataCacheSize);
        public Builder setStorageOptions(Map<String, String> storageOptions);
        public Builder setSerializedManifest(ByteBuffer serializedManifest);
        public Builder setStorageOptionsProvider(StorageOptionsProvider provider);
        public ReadOptions build();
    }
}

Import

import org.lance.ReadOptions;

I/O Contract

Builder Parameters

Method	Type	Default	Description
setVersion()	long	Empty (latest)	Dataset version to read; if not set, reads latest version
setBlockSize()	int	Empty	Minimum I/O request size hint in bytes; recommended > 4KB
setIndexCacheSizeBytes()	long	6 GiB	LRU index cache size in bytes
setMetadataCacheSizeBytes()	long	1 GiB	Metadata cache size in bytes; 0 disables caching
setStorageOptions()	Map<String, String>	Empty map	Storage connection parameters (credentials, endpoint)
setSerializedManifest()	ByteBuffer	Empty	Pre-serialized manifest for IPC scenarios
setStorageOptionsProvider()	StorageOptionsProvider	Empty	Provider for automatic credential refresh

Getter Return Values

Method	Return Type	Description
getVersion()	Optional<Long>	The configured version, or empty for latest
getBlockSize()	Optional<Integer>	The configured block size, or empty
getIndexCacheSizeBytes()	long	Index cache size in bytes
getMetadataCacheSizeBytes()	long	Metadata cache size in bytes
getStorageOptions()	Map<String, String>	Storage connection parameters
getSerializedManifest()	Optional<ByteBuffer>	Serialized manifest or empty
getStorageOptionsProvider()	Optional<StorageOptionsProvider>	Storage options provider or empty

Usage Examples

import org.lance.ReadOptions;
import java.util.HashMap;
import java.util.Map;

// Read with default options (latest version, default cache sizes)
ReadOptions defaults = new ReadOptions.Builder().build();

// Read a specific version with custom cache sizes
ReadOptions options = new ReadOptions.Builder()
    .setVersion(10)
    .setBlockSize(65536)
    .setIndexCacheSizeBytes(2L * 1024 * 1024 * 1024)   // 2 GiB
    .setMetadataCacheSizeBytes(512L * 1024 * 1024)       // 512 MiB
    .build();

// Read from S3 with credentials
Map<String, String> storageOpts = new HashMap<>();
storageOpts.put("aws_access_key_id", "AKIAIOSFODNN7EXAMPLE");
storageOpts.put("aws_secret_access_key", "...");
storageOpts.put("region", "us-east-1");

ReadOptions s3Options = new ReadOptions.Builder()
    .setStorageOptions(storageOpts)
    .build();

// Use with OpenDatasetBuilder
Dataset dataset = Dataset.open()
    .uri("s3://bucket/dataset.lance")
    .readOptions(s3Options)
    .build();

Related Pages

• Lance_format_Lance_Java_OpenDatasetBuilder - Consumes ReadOptions to configure dataset opening behavior
• Lance_format_Lance_Java_WriteParams - Analogous configuration class for write operations