Implementation:Lance format Lance RestApi

Knowledge Sources	Lance
Domains	REST_API, Namespace
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The RestApi specification (rest.yaml) is an OpenAPI 3.1.1 document that defines the Lance Namespace REST API. The specification serves a dual purpose:

1. Schema definitions (components/schemas, components/responses, tags) -- Define the request and response shapes for all Lance Namespace operations across all implementations (Rust, Python, Java, REST)
2. REST server paths (servers, security, paths, components/parameters) -- Define the complete REST server implementation for the Lance REST Namespace

The API is organized into the following tag groups:

• Namespace -- Create, list, describe, drop, and check existence of namespaces
• Table -- Full table lifecycle including create, register, declare, describe, list, drop, rename, restore, and schema operations
• Index -- Create, drop, list, and describe table indices (including scalar index creation)
• Tag -- Create, update, delete, list table tags, and get tag versions
• Transaction -- Alter and describe transactions
• Metadata -- Lightweight operations on object metadata
• Data -- Computationally intensive operations on object data (insert, delete, update, merge-insert, query, count rows)

Security is provided via OAuth2 and Bearer token authentication.

Server configuration supports customizable scheme, host, port, and base path.

Usage

This specification is used to:

• Generate client libraries (e.g., lance_namespace_reqwest_client)
• Generate server stubs for REST namespace implementations
• Define the canonical request/response types used by the LanceNamespace trait

Code Reference

Source Location

docs/src/rest.yaml

Signature

The API defines the following primary path groups:

# Namespace operations
POST   /v1/namespace/{id}/create
GET    /v1/namespace/{id}/list
POST   /v1/namespace/{id}/describe
POST   /v1/namespace/{id}/drop
HEAD   /v1/namespace/{id}/exists

# Table operations
POST   /v1/namespace/{id}/table/{table_id}/create
POST   /v1/namespace/{id}/table/{table_id}/register
POST   /v1/namespace/{id}/table/{table_id}/describe
GET    /v1/namespace/{id}/table/list
POST   /v1/namespace/{id}/table/{table_id}/drop
POST   /v1/namespace/{id}/table/{table_id}/rename

# Data operations
POST   /v1/namespace/{id}/table/{table_id}/insert
POST   /v1/namespace/{id}/table/{table_id}/delete
POST   /v1/namespace/{id}/table/{table_id}/update
POST   /v1/namespace/{id}/table/{table_id}/merge-insert
POST   /v1/namespace/{id}/table/{table_id}/query
POST   /v1/namespace/{id}/table/{table_id}/count-rows

# Index operations
POST   /v1/namespace/{id}/table/{table_id}/index/create
POST   /v1/namespace/{id}/table/{table_id}/index/{index_id}/drop
GET    /v1/namespace/{id}/table/{table_id}/index/list

# Tag operations
POST   /v1/namespace/{id}/table/{table_id}/tag/create
POST   /v1/namespace/{id}/table/{table_id}/tag/{tag_name}/update
POST   /v1/namespace/{id}/table/{table_id}/tag/{tag_name}/delete
GET    /v1/namespace/{id}/table/{table_id}/tag/list

Import

The REST API specification is not imported directly in Rust code. Instead, generated client models are imported:

use lance_namespace_reqwest_client::models::{
    CreateNamespaceRequest, CreateNamespaceResponse,
    ListTablesRequest, ListTablesResponse,
    // ... etc.
};

I/O Contract

Common Request Parameters

Parameter	Location	Type	Description
id	path	string	Namespace identifier (hierarchical, using delimiter)
table_id	path	string	Table name within the namespace
delimiter	query	string	Namespace hierarchy delimiter (default: /)
page_token	query	string	Pagination token for list operations
limit	query	integer	Maximum number of results per page

Common Response Codes

Code	Description
200	Success
400	Bad request / Invalid input
401	Unauthenticated
403	Permission denied
404	Resource not found
406	Unsupported operation
409	Conflict (already exists, concurrent modification)
503	Service unavailable
5XX	Internal server error

Authentication

Scheme	Type	Description
OAuth2	OAuth 2.0	Standard OAuth2 flow
BearerAuth	HTTP Bearer	Bearer token authentication

Usage Examples

# Create a namespace
curl -X POST http://localhost:2333/v1/namespace/my_ns/create \
  -H "Content-Type: application/json" \
  -d '{"properties": {"owner": "team-ml"}}'

# List tables in a namespace
curl http://localhost:2333/v1/namespace/my_ns/table/list

# Create a table
curl -X POST http://localhost:2333/v1/namespace/my_ns/table/my_table/create \
  -H "Content-Type: application/json" \
  -d '{"schema": {"fields": [{"name": "id", "type": {"type": "int64"}, "nullable": false}]}}'

# Query a table
curl -X POST http://localhost:2333/v1/namespace/my_ns/table/my_table/query \
  -H "Content-Type: application/json" \
  -d '{"filter": "id > 100", "limit": 10}'

Related Pages

• Lance_format_Lance_LanceNamespaceTrait -- Rust trait that mirrors these REST operations
• Lance_format_Lance_NamespaceError -- Error codes used across REST responses
• Lance_format_Lance_NamespaceSchema -- Schema conversion for JSON Arrow types used in requests