Implementation:Lance format Lance Java RestNamespace

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

Overview

The RestNamespace class provides a REST API-based implementation of the LanceNamespace interface, enabling namespace and table management operations through HTTP endpoints with support for TLS and dynamic authentication headers.

Description

RestNamespace implements LanceNamespace and Closeable, wrapping a native Rust implementation via JNI. It communicates with a remote namespace service over HTTP/HTTPS, serializing all requests and responses as JSON. The class supports:

Namespace operations:

• listNamespaces, describeNamespace, createNamespace, dropNamespace, namespaceExists

Table operations:

• listTables, describeTable, createTable, createEmptyTable, declareTable, renameTable
• registerTable, deregisterTable, dropTable, tableExists
• insertIntoTable, mergeInsertIntoTable, updateTable, deleteFromTable
• queryTable, countTableRows

Index operations:

• createTableIndex, listTableIndices, describeTableIndexStats

Transaction operations:

• describeTransaction, alterTransaction

Configuration properties:

• uri (required): REST API endpoint URL
• delimiter (optional): Namespace delimiter (default: "$")
• header.*: Static HTTP headers (e.g., header.Authorization=Bearer token)
• tls.cert_file: Path to client certificate file
• tls.key_file: Path to client key file
• tls.ssl_ca_cert: Path to CA certificate file
• tls.assert_hostname: Enable/disable hostname verification (default: true)

Dynamic context provider:

• Supports DynamicContextProvider for per-request context (e.g., dynamic auth headers)
• Context keys prefixed with headers. are converted to HTTP headers
• Can be loaded from classpath via dynamic_context_provider.impl property

Usage

Use RestNamespace when you need to manage Lance tables through a centralized REST catalog service. This is the appropriate namespace implementation for production environments with centralized table management, multi-tenant access control, and dynamic authentication.

Code Reference

Source Location

Property	Value
File	java/src/main/java/org/lance/namespace/RestNamespace.java
Package	org.lance.namespace
Lines	503

Signature

public class RestNamespace implements LanceNamespace, Closeable

Import

import org.lance.namespace.RestNamespace;

I/O Contract

Lifecycle Methods

Method	Input	Output	Description
RestNamespace()	none	instance	Creates uninitialized namespace
initialize(Map, BufferAllocator)	properties, allocator	void	Initializes with config properties
initialize(Map, BufferAllocator, DynamicContextProvider)	properties, allocator, provider	void	Initializes with dynamic context provider
close()	none	void	Releases native resources

Key Namespace Operations

Method	Input	Output	Description
namespaceId()	none	String	Returns the namespace identifier
listNamespaces(ListNamespacesRequest)	request	ListNamespacesResponse	Lists child namespaces
createNamespace(CreateNamespaceRequest)	request	CreateNamespaceResponse	Creates a namespace
dropNamespace(DropNamespaceRequest)	request	DropNamespaceResponse	Drops a namespace

Key Table Operations

Method	Input	Output	Description
listTables(ListTablesRequest)	request	ListTablesResponse	Lists tables
describeTable(DescribeTableRequest)	request	DescribeTableResponse	Describes a table
declareTable(DeclareTableRequest)	request	DeclareTableResponse	Declares a table location
createTable(CreateTableRequest, byte[])	request, data	CreateTableResponse	Creates a table with data
renameTable(RenameTableRequest)	request	RenameTableResponse	Renames a table
dropTable(DropTableRequest)	request	DropTableResponse	Drops a table
queryTable(QueryTableRequest)	request	byte[]	Queries table data

Usage Examples

Basic REST Namespace with Authentication

import org.lance.namespace.RestNamespace;
import org.lance.namespace.model.*;
import org.apache.arrow.memory.RootAllocator;
import java.util.HashMap;
import java.util.Map;

Map<String, String> properties = new HashMap<>();
properties.put("uri", "https://api.example.com");
properties.put("delimiter", ".");
properties.put("header.Authorization", "Bearer my-token");

RestNamespace namespace = new RestNamespace();
namespace.initialize(properties, new RootAllocator(Long.MAX_VALUE));

// List tables
ListTablesRequest request = new ListTablesRequest();
ListTablesResponse response = namespace.listTables(request);

namespace.close();

REST Namespace with TLS Client Certificates

import org.lance.namespace.RestNamespace;
import java.util.HashMap;
import java.util.Map;

Map<String, String> properties = new HashMap<>();
properties.put("uri", "https://secure-api.example.com");
properties.put("tls.cert_file", "/path/to/client-cert.pem");
properties.put("tls.key_file", "/path/to/client-key.pem");
properties.put("tls.ssl_ca_cert", "/path/to/ca-cert.pem");

RestNamespace namespace = new RestNamespace();
namespace.initialize(properties, allocator);
// Use namespace for operations...
namespace.close();

Dynamic Authentication Headers

import org.lance.namespace.RestNamespace;
import org.lance.namespace.DynamicContextProvider;
import java.util.HashMap;
import java.util.Map;

// Custom provider that refreshes auth tokens per request
DynamicContextProvider authProvider = () -> {
    Map<String, String> context = new HashMap<>();
    context.put("headers.Authorization", "Bearer " + fetchFreshToken());
    return context;
};

Map<String, String> properties = new HashMap<>();
properties.put("uri", "https://api.example.com");

RestNamespace namespace = new RestNamespace();
namespace.initialize(properties, allocator, authProvider);
// Each operation now gets a fresh auth token
namespace.close();

Using with Dataset Operations

import org.lance.Dataset;
import org.lance.WriteParams;
import java.util.Arrays;

// Write a dataset through the REST namespace
Dataset dataset = Dataset.write()
    .reader(myArrowReader)
    .namespace(namespace)
    .tableId(Arrays.asList("catalog", "my_table"))
    .mode(WriteParams.WriteMode.CREATE)
    .execute();

// Open a dataset through the REST namespace
Dataset existing = Dataset.open()
    .namespace(namespace)
    .tableId(Arrays.asList("catalog", "my_table"))
    .build();

Related Pages

• Lance_format_Lance_Java_DirectoryNamespace - Directory-based namespace implementation
• Lance_format_Lance_Java_Dataset - Dataset class that integrates with namespaces
• Lance_format_Lance_Java_WriteDatasetBuilder - Builder that uses namespaces for write operations