com.lancedb.lance.namespace

Class LanceNamespaceStorageOptionsProvider

java.lang.Object

com.lancedb.lance.namespace.LanceNamespaceStorageOptionsProvider

All Implemented Interfaces:

StorageOptionsProvider

public class LanceNamespaceStorageOptionsProvider
extends Object
implements StorageOptionsProvider

Storage options provider that fetches storage options from a LanceNamespace.

This provider automatically fetches fresh storage options by calling the namespace's describeTable() method, which returns both the table location and time-limited storage options. This is currently only used for refreshing AWS temporary access credentials.

This is the recommended approach for LanceDB Cloud and other namespace-based deployments, as it handles storage options refresh automatically.

Example Usage

 // 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()
 );
 

Constructor Summary

Constructors

Constructor and Description
LanceNamespaceStorageOptionsProvider(com.lancedb.lance.namespace.LanceNamespace namespace, List<String> tableId) Create a storage options provider that fetches storage options from a LanceNamespace.

Method Summary

Modifier and Type	Method and Description
Map<String,String>	fetchStorageOptions() Fetch credentials from the namespace.
String	providerId() Return a human-readable unique identifier for this provider instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LanceNamespaceStorageOptionsProvider

public LanceNamespaceStorageOptionsProvider(com.lancedb.lance.namespace.LanceNamespace namespace,
                                            List<String> tableId)

Create a storage options provider that fetches storage options from a LanceNamespace.

Parameters:

namespace - The namespace instance to fetch storage options from

tableId - The table identifier (e.g., ["workspace", "table_name"])

Method Detail

fetchStorageOptions

public Map<String,String> fetchStorageOptions()

Fetch credentials from the namespace.

This calls namespace.describeTable() to get the latest credentials and their expiration time.

Specified by:

fetchStorageOptions in interface StorageOptionsProvider

Returns:

Flat map of string key-value pairs containing credentials and expires_at_millis

Throws:

RuntimeException - if the namespace doesn't return storage credentials or expiration time

providerId

public String providerId()

Return a human-readable unique identifier for this provider instance.

This creates a semantic ID based on the namespace's ID and the table ID, enabling proper equality comparison and caching.

Specified by:

providerId in interface StorageOptionsProvider

Returns:

A human-readable unique identifier string combining namespace and table info