openapi: 3.1.1
info:
title: Lance Namespace Specification Data Index API
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
description: 'This OpenAPI specification is a part of the Lance namespace specification. It contains 2 parts:
The `components/schemas`, `components/responses`, `components/examples`, `tags` sections define
the request and response shape for each operation in a Lance Namespace across all implementations.
See https://lance.org/format/namespace/operations for more details.
The `servers`, `security`, `paths`, `components/parameters` sections are for the
Lance REST Namespace implementation, which defines a complete REST server that can work with Lance datasets.
See https://lance.org/format/namespace/rest for more details.
'
servers:
- url: '{scheme}://{host}:{port}/{basePath}'
description: Generic server URL with all parts configurable
variables:
scheme:
default: http
host:
default: localhost
port:
default: '2333'
basePath:
default: ''
- url: '{scheme}://{host}/{basePath}'
description: Server URL when the port can be inferred from the scheme
variables:
scheme:
default: http
host:
default: localhost
basePath:
default: ''
security:
- OAuth2: []
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Index
description: 'Operations that are related to an index
'
paths:
/v1/table/{id}/create_index:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Index
summary: Create an index on a table
operationId: CreateTableIndex
description: 'Create an index on a table column for faster search operations.
Supports vector indexes (IVF_FLAT, IVF_HNSW_SQ, IVF_PQ, etc.) and scalar indexes (BTREE, BITMAP, FTS, etc.).
Index creation is handled asynchronously.
Use the `ListTableIndices` and `DescribeTableIndexStats` operations to monitor index creation progress.
'
requestBody:
description: Index creation request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableIndexRequest'
required: true
responses:
200:
$ref: '#/components/responses/CreateTableIndexResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/table/{id}/create_scalar_index:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Index
summary: Create a scalar index on a table
operationId: CreateTableScalarIndex
description: 'Create a scalar index on a table column for faster filtering operations.
Supports scalar indexes (BTREE, BITMAP, LABEL_LIST, FTS, etc.).
This is an alias for CreateTableIndex specifically for scalar indexes.
Index creation is handled asynchronously.
Use the `ListTableIndices` and `DescribeTableIndexStats` operations to monitor index creation progress.
'
requestBody:
description: Scalar index creation request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableIndexRequest'
required: true
responses:
200:
$ref: '#/components/responses/CreateTableScalarIndexResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/table/{id}/index/list:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Index
summary: List indexes on a table
operationId: ListTableIndices
description: 'List all indices created on a table. Returns information about each index
including name, columns, status, and UUID.
'
requestBody:
description: Index list request
content:
application/json:
schema:
$ref: '#/components/schemas/ListTableIndicesRequest'
required: true
responses:
200:
$ref: '#/components/responses/ListTableIndicesResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/table/{id}/index/{index_name}/stats:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
- name: index_name
in: path
description: Name of the index to get stats for
required: true
schema:
type: string
post:
tags:
- Index
summary: Get table index statistics
operationId: DescribeTableIndexStats
description: 'Get statistics for a specific index on a table. Returns information about
the index type, distance type (for vector indices), and row counts.
'
requestBody:
description: Index stats request
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeTableIndexStatsRequest'
required: true
responses:
200:
$ref: '#/components/responses/DescribeTableIndexStatsResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/table/{id}/index/{index_name}/drop:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
- name: index_name
in: path
description: Name of the index to drop
required: true
schema:
type: string
post:
tags:
- Index
summary: Drop a specific index
operationId: DropTableIndex
description: 'Drop the specified index from table `id`.
REST NAMESPACE ONLY
REST namespace does not use a request body for this operation.
The `DropTableIndexRequest` information is passed in the following way:
- `id`: pass through path parameter of the same name
- `index_name`: pass through path parameter of the same name
'
responses:
200:
$ref: '#/components/responses/DropTableIndexResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
components:
schemas:
DropTableIndexResponse:
type: object
description: Response for drop index operation
properties:
transaction_id:
type: string
description: Optional transaction identifier
CreateTableIndexRequest:
type: object
required:
- column
- index_type
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
column:
type: string
description: Name of the column to create index on
index_type:
type: string
description: Type of index to create (e.g., BTREE, BITMAP, LABEL_LIST, IVF_FLAT, IVF_PQ, IVF_HNSW_SQ, FTS)
name:
type: string
nullable: true
description: Optional name for the index. If not provided, a name will be auto-generated.
distance_type:
type: string
description: Distance metric type for vector indexes (e.g., l2, cosine, dot)
with_position:
type: boolean
nullable: true
description: Optional FTS parameter for position tracking
base_tokenizer:
type: string
nullable: true
description: Optional FTS parameter for base tokenizer
language:
type: string
nullable: true
description: Optional FTS parameter for language
max_token_length:
type: integer
nullable: true
minimum: 0
description: Optional FTS parameter for maximum token length
lower_case:
type: boolean
nullable: true
description: Optional FTS parameter for lowercase conversion
stem:
type: boolean
nullable: true
description: Optional FTS parameter for stemming
remove_stop_words:
type: boolean
nullable: true
description: Optional FTS parameter for stop word removal
ascii_folding:
type: boolean
nullable: true
description: Optional FTS parameter for ASCII folding
ListTableIndicesRequest:
type: object
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
description: The namespace identifier
version:
type: integer
format: int64
minimum: 0
nullable: true
description: Optional table version to list indexes from
page_token:
$ref: '#/components/schemas/PageToken'
limit:
$ref: '#/components/schemas/PageLimit'
Identity:
type: object
description: 'Identity information of a request.
'
properties:
api_key:
type: string
description: 'API key for authentication.
REST NAMESPACE ONLY
This is passed via the `x-api-key` header.
'
auth_token:
type: string
description: 'Bearer token for authentication.
REST NAMESPACE ONLY
This is passed via the `Authorization` header
with the Bearer scheme (e.g., `Bearer <token>`).
'
IndexContent:
type: object
required:
- index_name
- index_uuid
- columns
- status
properties:
index_name:
type: string
description: Name of the index
index_uuid:
type: string
description: Unique identifier for the index
columns:
type: array
items:
type: string
description: Columns covered by this index
status:
type: string
description: Current status of the index
DescribeTableIndexStatsResponse:
type: object
properties:
distance_type:
type: string
nullable: true
description: Distance type for vector indexes
index_type:
type: string
nullable: true
description: Type of the index
num_indexed_rows:
type: integer
format: int64
minimum: 0
nullable: true
description: Number of indexed rows
num_unindexed_rows:
type: integer
format: int64
minimum: 0
nullable: true
description: Number of unindexed rows
num_indices:
type: integer
format: int32
minimum: 0
nullable: true
description: Number of indices
DescribeTableIndexStatsRequest:
type: object
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
version:
type: integer
format: int64
minimum: 0
nullable: true
description: Optional table version to get stats for
index_name:
type: string
description: Name of the index
PageLimit:
description: 'An inclusive upper bound of the
number of results that a caller will receive.
'
type: integer
nullable: true
ErrorResponse:
type: object
description: Common JSON error response model
required:
- code
properties:
error:
type: string
description: A brief, human-readable message about the error.
example: Table 'users' not found in namespace 'production'
code:
type: integer
minimum: 0
description: "Lance Namespace error code identifying the error type.\n\nError codes:\n 0 - Unsupported: Operation not supported by this backend\n 1 - NamespaceNotFound: The specified namespace does not exist\n 2 - NamespaceAlreadyExists: A namespace with this name already exists\n 3 - NamespaceNotEmpty: Namespace contains tables or child namespaces\n 4 - TableNotFound: The specified table does not exist\n 5 - TableAlreadyExists: A table with this name already exists\n 6 - TableIndexNotFound: The specified table index does not exist\n 7 - TableIndexAlreadyExists: A table index with this name already exists\n 8 - TableTagNotFound: The specified table tag does not exist\n 9 - TableTagAlreadyExists: A table tag with this name already exists\n 10 - TransactionNotFound: The specified transaction does not exist\n 11 - TableVersionNotFound: The specified table version does not exist\n 12 - TableColumnNotFound: The specified table column does not exist\n 13 - InvalidInput: Malformed request or invalid parameters\n 14 - ConcurrentModification: Optimistic concurrency conflict\n 15 - PermissionDenied: User lacks permission for this operation\n 16 - Unauthenticated: Authentication credentials are missing or invalid\n 17 - ServiceUnavailable: Service is temporarily unavailable\n 18 - Internal: Unexpected server/implementation error\n 19 - InvalidTableState: Table is in an invalid state for the operation\n 20 - TableSchemaValidationError: Table schema validation failed\n"
example: 4
detail:
type: string
description: 'An optional human-readable explanation of the error.
This can be used to record additional information such as stack trace.
'
example: The table may have been dropped or renamed
instance:
type: string
description: 'A string that identifies the specific occurrence of the error.
This can be a URI, a request or response ID,
or anything that the implementation can recognize to trace specific occurrence of the error.
'
example: /v1/table/production$users/describe
CreateTableIndexResponse:
type: object
description: Response for create index operation
properties:
transaction_id:
type: string
description: Optional transaction identifier
Context:
type: object
description: 'Arbitrary context for a request as key-value pairs.
How to use the context is custom to the specific implementation.
REST NAMESPACE ONLY
Context entries are passed via HTTP headers using the naming convention
`x-lance-ctx-<key>: <value>`. For example, a context entry
`{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`.
'
additionalProperties:
type: string
CreateTableScalarIndexResponse:
type: object
description: Response for create scalar index operation
properties:
transaction_id:
type: string
description: Optional transaction identifier
PageToken:
description: 'An opaque token that allows pagination for list operations (e.g. ListNamespaces).
For an initial request of a list operation,
if the implementation cannot return all items in one response,
or if there are more items than the page limit specified in the request,
the implementation must return a page token in the response,
indicating there are more results available.
After the initial request,
the value of the page token from each response must be used
as the page token value for the next request.
Caller must interpret either `null`,
missing value or empty string value of the page token from
the implementation''s response as the end of the listing results.
'
type: string
nullable: true
ListTableIndicesResponse:
type: object
required:
- indexes
properties:
indexes:
type: array
items:
$ref: '#/components/schemas/IndexContent'
description: List of indexes on the table
page_token:
$ref: '#/components/schemas/PageToken'
responses:
ServerErrorResponse:
description: A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/server-error
title: Internal Server Error
status: 500
detail: ''
instance: /v1/namespaces
BadRequestErrorResponse:
description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/bad-request
title: Malformed request
status: 400
detail: ''
instance: /v1/namespaces
ListTableIndicesResponse:
description: List of indices on the table
content:
application/json:
schema:
$ref: '#/components/schemas/ListTableIndicesResponse'
DropTableIndexResponse:
description: Index drop operation result
content:
application/json:
schema:
$ref: '#/components/schemas/DropTableIndexResponse'
CreateTableIndexResponse:
description: Index created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableIndexResponse'
ServiceUnavailableErrorResponse:
description: The service is not ready to handle the request. The client should wait and retry. The service may additionally send a Retry-After header to indicate when to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/service-unavailable
title: Slow down
status: 503
detail: ''
instance: /v1/namespaces
ForbiddenErrorResponse:
description: Forbidden. Authenticated user does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/forbidden-request
title: Not authorized to make this request
status: 403
detail: ''
instance: /v1/namespaces
UnauthorizedErrorResponse:
description: Unauthorized. The request lacks valid authentication credentials for the operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/unauthorized-request
title: No valid authentication credentials for the operation
status: 401
detail: ''
instance: /v1/namespaces
NotFoundErrorResponse:
description: A server-side problem that means can not find the specified resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/not-found-error
title: Not found Error
status: 404
detail: ''
instance: /v1/namespaces/{ns}
CreateTableScalarIndexResponse:
description: Scalar index created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableScalarIndexResponse'
DescribeTableIndexStatsResponse:
description: Index statistics
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeTableIndexStatsResponse'
parameters:
id:
name: id
description: '`string identifier` of an object in a namespace, following the Lance Namespace spec.
When the value is equal to the delimiter, it represents the root namespace.
For example, `v1/namespace/$/list` performs a `ListNamespace` on the root namespace.
'
in: path
required: true
schema:
type: string
delimiter:
name: delimiter
description: 'An optional delimiter of the `string identifier`, following the Lance Namespace spec.
When not specified, the `$` delimiter must be used.
'
in: query
required: false
schema:
type: string
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: /oauth/token
scopes: {}
BearerAuth:
type: http
scheme: bearer
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key