Struct DirectoryNamespaceBuilder 

pub struct DirectoryNamespaceBuilder { /* private fields */ }

Builder for creating a DirectoryNamespace.

This builder provides a fluent API for configuring and establishing connections to directory-based Lance namespaces.

Examples

// Create a local directory namespace
let namespace = DirectoryNamespaceBuilder::new("/path/to/data")
    .build()
    .await?;

// Create with custom storage options and session
let session = Arc::new(Session::default());
let namespace = DirectoryNamespaceBuilder::new("s3://bucket/path")
    .storage_option("region", "us-west-2")
    .storage_option("access_key_id", "key")
    .session(session)
    .build()
    .await?;

Implementations

impl DirectoryNamespaceBuilder

pub fn new(root: impl Into<String>) -> Self

Create a new DirectoryNamespaceBuilder with the specified root path.

Arguments

• root - Root directory path (local path or cloud URI like s3://bucket/path)

pub fn manifest_enabled(self, enabled: bool) -> Self

Enable or disable manifest-based listing.

When enabled (default), the namespace uses a __manifest table to track tables. When disabled, relies solely on directory scanning.

pub fn dir_listing_enabled(self, enabled: bool) -> Self

Enable or disable directory-based listing fallback.

When enabled (default), falls back to directory scanning for tables not in the manifest. When disabled, only consults the manifest table.

pub fn inline_optimization_enabled(self, enabled: bool) -> Self

Enable or disable inline optimization of the __manifest table.

When enabled (default), performs compaction and indexing on the __manifest table after every write operation to maintain optimal performance. When disabled, manual optimization must be performed separately.

pub fn from_properties( properties: HashMap<String, String>, session: Option<Arc<Session>>, ) -> Result<Self>

Create a DirectoryNamespaceBuilder from properties HashMap.

This method parses a properties map into builder configuration. It expects:

• root: The root directory path (required)
• manifest_enabled: Enable manifest-based table tracking (optional, default: true)
• dir_listing_enabled: Enable directory listing for table discovery (optional, default: true)
• inline_optimization_enabled: Enable inline optimization of __manifest table (optional, default: true)
• storage.*: Storage options (optional, prefix will be stripped)

Credential vendor properties (prefixed with credential_vendor., prefix is stripped):

• credential_vendor.enabled: Set to “true” to enable credential vending (required)
• credential_vendor.permission: Permission level: read, write, or admin (default: read)

AWS-specific properties (for s3:// locations):

• credential_vendor.aws_role_arn: AWS IAM role ARN (required for AWS)
• credential_vendor.aws_external_id: AWS external ID (optional)
• credential_vendor.aws_region: AWS region (optional)
• credential_vendor.aws_role_session_name: AWS role session name (optional)
• credential_vendor.aws_duration_millis: Credential duration in ms (default: 3600000, range: 15min-12hrs)

GCP-specific properties (for gs:// locations):

• credential_vendor.gcp_service_account: Service account to impersonate (optional)

Note: GCP uses Application Default Credentials (ADC). To use a service account key file, set the GOOGLE_APPLICATION_CREDENTIALS environment variable before starting. GCP token duration cannot be configured; it’s determined by the STS endpoint (typically 1 hour).

Azure-specific properties (for az:// locations):

• credential_vendor.azure_account_name: Azure storage account name (required for Azure)
• credential_vendor.azure_tenant_id: Azure tenant ID (optional)
• credential_vendor.azure_duration_millis: Credential duration in ms (default: 3600000, up to 7 days)

Arguments

• properties - Configuration properties
• session - Optional Lance session to reuse object store registry

Returns

Returns a DirectoryNamespaceBuilder instance.

Errors

Returns an error if the root property is missing.

Examples

let mut properties = HashMap::new();
properties.insert("root".to_string(), "/path/to/data".to_string());
properties.insert("manifest_enabled".to_string(), "true".to_string());
properties.insert("dir_listing_enabled".to_string(), "false".to_string());
properties.insert("storage.region".to_string(), "us-west-2".to_string());

let namespace = DirectoryNamespaceBuilder::from_properties(properties, None)?
    .build()
    .await?;

pub fn storage_option( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Add a storage option.

Arguments

• key - Storage option key (e.g., “region”, “access_key_id”)
• value - Storage option value

pub fn storage_options(self, options: HashMap<String, String>) -> Self

Add multiple storage options.

Arguments

• options - HashMap of storage options to add

pub fn session(self, session: Arc<Session>) -> Self

Set the Lance session to use for this namespace.

When a session is provided, the namespace will reuse the session’s object store registry, allowing multiple namespaces and datasets to share the same underlying storage connections.

Arguments

• session - Arc-wrapped Lance session

pub fn credential_vendor_property( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Add a credential vendor property.

Use short property names without the credential_vendor. prefix. Common properties: enabled, permission. AWS properties: aws_role_arn, aws_external_id, aws_region, aws_role_session_name, aws_duration_millis. GCP properties: gcp_service_account. Azure properties: azure_account_name, azure_tenant_id, azure_duration_millis.

Arguments

• key - Property key (e.g., “enabled”, “aws_role_arn”)
• value - Property value

Example

let namespace = DirectoryNamespaceBuilder::new("s3://my-bucket/data")
    .credential_vendor_property("enabled", "true")
    .credential_vendor_property("aws_role_arn", "arn:aws:iam::123456789012:role/MyRole")
    .credential_vendor_property("permission", "read")
    .build()
    .await?;

pub fn credential_vendor_properties( self, properties: HashMap<String, String>, ) -> Self

Add multiple credential vendor properties.

Use short property names without the credential_vendor. prefix.

Arguments

• properties - HashMap of credential vendor properties to add

pub fn context_provider(self, provider: Arc<dyn DynamicContextProvider>) -> Self

Set a dynamic context provider for per-request context.

The provider can be used to generate additional context for operations. For DirectoryNamespace, the context is stored but not directly used in operations (unlike RestNamespace where it’s converted to HTTP headers).

Arguments

• provider - The context provider implementation

pub async fn build(self) -> Result<DirectoryNamespace>

Build the DirectoryNamespace.

Returns

Returns a DirectoryNamespace instance.

Errors

Returns an error if:

• The root path is invalid
• Connection to the storage backend fails
• Storage options are invalid

Trait Implementations

impl Clone for DirectoryNamespaceBuilder

fn clone(&self) -> DirectoryNamespaceBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DirectoryNamespaceBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.