Implementation:Lance format Lance Java NamespaceStorageOptions

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

Overview

Description

The LanceNamespaceStorageOptionsProvider class implements the StorageOptionsProvider interface by fetching storage credentials from a LanceNamespace instance. It calls the namespace's describeTable() method to retrieve both the table location and time-limited storage options, providing automatic credential refresh for namespace-based deployments such as LanceDB Cloud.

The class takes a LanceNamespace reference and a table identifier (as a list of strings) at construction time. On each fetchStorageOptions() call, it constructs a DescribeTableRequest, invokes the namespace, and extracts the storageOptions map from the response. If no storage options are returned, it throws a RuntimeException.

The providerId() method returns a semantic identifier combining the namespace ID and table ID, enabling proper caching and equality comparison in the object store registry.

Usage

Use LanceNamespaceStorageOptionsProvider as the recommended approach for LanceDB Cloud and other namespace-based deployments. It handles credential vending and refresh automatically without requiring custom credential management logic.

Code Reference

Source Location

java/src/main/java/org/lance/namespace/LanceNamespaceStorageOptionsProvider.java

Signature

public class LanceNamespaceStorageOptionsProvider implements StorageOptionsProvider {
    public LanceNamespaceStorageOptionsProvider(LanceNamespace namespace, List<String> tableId);
    public Map<String, String> fetchStorageOptions();
    public String providerId();
}

Import

import org.lance.namespace.LanceNamespaceStorageOptionsProvider;

I/O Contract

Constructor Inputs

Parameter	Type	Required	Description
namespace	LanceNamespace	Yes	The namespace instance to fetch storage options from
tableId	List<String>	Yes	The table identifier (e.g., ["workspace", "table_name"])

Outputs

Method	Return Type	Description
fetchStorageOptions()	Map<String, String>	Flat map of storage credentials from the namespace's describeTable response. May include expires_at_millis for auto-refresh.
providerId()	String	Semantic ID in format "LanceNamespaceStorageOptionsProvider { namespace: ..., table_id: ... }"

Exceptions

Exception	Condition
RuntimeException	Thrown when the namespace does not return storage_options in the describeTable response

Usage Examples

// Connect to a namespace (e.g., LanceDB Cloud)
LanceNamespace namespace = LanceNamespaces.connect("rest", Map.of(
    "url", "https://api.lancedb.com",
    "api_key", "your-api-key"
));

// Create storage options provider
LanceNamespaceStorageOptionsProvider provider =
    new LanceNamespaceStorageOptionsProvider(
        namespace,
        Arrays.asList("workspace", "table_name")
    );

// Use with dataset - storage options auto-refresh
Dataset dataset = Dataset.open(
    "s3://bucket/table.lance",
    new ReadOptions.Builder()
        .setStorageOptionsProvider(provider)
        .build()
);

Related Pages

• Lance_format_Lance_Java_StorageOptionsProvider -- The interface this class implements
• Lance_format_Lance_Java_DynamicContextProvider -- Per-request context provider for namespace operations
• Lance_format_Lance_Java_RestAdapter -- REST adapter for testing namespace implementations