openapi: 3.1.1
info:
title: Lance Namespace Specification Data Transaction 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: Transaction
description: 'Operations that are related to a transaction
'
paths:
/v1/table/batch-commit:
parameters:
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Transaction
summary: Atomically commit a batch of mixed table operations
operationId: BatchCommitTables
description: 'Atomically commit a batch of table operations. This is a generalized version
of `BatchCreateTableVersions` that supports mixed operation types within a
single atomic transaction at the metadata layer.
Supported operation types:
- `DeclareTable`: Declare (reserve) a new table
- `CreateTableVersion`: Create a new version entry for a table
- `DeleteTableVersions`: Delete version ranges from a table
- `DeregisterTable`: Deregister (soft-delete) a table
All operations are committed atomically: either all succeed or none are applied.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCommitTablesRequest'
responses:
200:
$ref: '#/components/responses/BatchCommitTablesResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
409:
$ref: '#/components/responses/ConflictErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/transaction/{id}/describe:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Transaction
summary: Describe information about a transaction
operationId: DescribeTransaction
description: 'Return a detailed information for a given transaction
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeTransactionRequest'
responses:
200:
$ref: '#/components/responses/DescribeTransactionResponse'
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/transaction/{id}/alter:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Transaction
summary: Alter information of a transaction.
operationId: AlterTransaction
description: 'Alter a transaction with a list of actions such as setting status or properties.
The server should either succeed and apply all actions, or fail and apply no action.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AlterTransactionRequest'
responses:
200:
$ref: '#/components/responses/AlterTransactionResponse'
400:
$ref: '#/components/responses/BadRequestErrorResponse'
401:
$ref: '#/components/responses/UnauthorizedErrorResponse'
403:
$ref: '#/components/responses/ForbiddenErrorResponse'
404:
$ref: '#/components/responses/NotFoundErrorResponse'
409:
$ref: '#/components/responses/ConflictErrorResponse'
503:
$ref: '#/components/responses/ServiceUnavailableErrorResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
components:
schemas:
DeclareTableRequest:
type: object
description: 'Request for declaring a table.
'
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
location:
type: string
description: 'Optional storage location for the table.
If not provided, the namespace implementation should determine the table location.
'
vend_credentials:
description: 'Whether to include vended credentials in the response `storage_options`.
When true, the implementation should provide vended credentials for accessing storage.
When not set, the implementation can decide whether to return vended credentials.
'
type: boolean
properties:
type: object
description: 'Business logic properties stored and managed by the namespace implementation outside
Lance context, if supported by the implementation.
'
additionalProperties:
type: string
AlterTransactionAction:
type: object
description: 'A single action that could be performed to alter a transaction.
This action holds the model definition for all types of specific actions models,
this is to minimize difference and compatibility issue across codegen in different languages.
When used, only one of the actions should be non-null for each action.
If you would like to perform multiple actions, set a list of actions in the AlterTransactionRequest.
'
properties:
setStatusAction:
$ref: '#/components/schemas/AlterTransactionSetStatus'
setPropertyAction:
$ref: '#/components/schemas/AlterTransactionSetProperty'
unsetPropertyAction:
$ref: '#/components/schemas/AlterTransactionUnsetProperty'
DeclareTableResponse:
type: object
description: 'Response for declaring a table.
'
properties:
transaction_id:
type: string
description: Optional transaction identifier
location:
type: string
storage_options:
type: object
description: 'Configuration options to be used to access storage. The available
options depend on the type of storage in use. These will be
passed directly to Lance to initialize storage access.
'
additionalProperties:
type: string
properties:
type: object
description: 'If the implementation does not support table properties, it should return null for this field. Otherwise it should return the properties.
'
additionalProperties:
type: string
example:
owner: Ralph
created_at: '1452120468'
default: {}
nullable: true
managed_versioning:
type: boolean
description: 'When true, the caller should use namespace table version operations
(CreateTableVersion, BatchCreateTableVersions, DescribeTableVersion, ListTableVersions, BatchDeleteTableVersions)
to manage table versions instead of relying on Lance''s native version management.
'
BatchDeleteTableVersionsResponse:
type: object
description: Response for deleting table version records
properties:
deleted_count:
type: integer
format: int64
minimum: 0
description: Number of version records deleted
transaction_id:
type: string
description: Optional transaction identifier
ManifestNamingScheme:
type: string
description: "The naming scheme used for manifest files in the `_versions/` directory.\n\nKnown values:\n- `V1`: `_versions/{version}.manifest` - Simple version-based naming\n- `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number\n (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores\n\nV2 is preferred for new tables as it enables efficient latest-version discovery\nwithout needing to list all versions.\n"
example: V2
AlterTransactionRequest:
type: object
description: 'Alter a transaction with a list of actions.
The server should either succeed and apply all actions, or fail and apply no action.
'
required:
- actions
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
actions:
type: array
minItems: 1
items:
$ref: '#/components/schemas/AlterTransactionAction'
DescribeTransactionResponse:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/TransactionStatus'
properties:
type: object
additionalProperties:
type: string
DescribeTransactionRequest:
type: object
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
TableVersion:
type: object
required:
- version
- manifest_path
properties:
version:
type: integer
format: int64
minimum: 0
description: Version number
manifest_path:
type: string
description: Path to the manifest file for this version.
manifest_size:
type: integer
format: int64
minimum: 0
description: Size of the manifest file in bytes
e_tag:
type: string
description: 'Optional ETag for optimistic concurrency control.
Useful for S3 and similar object stores.
'
timestamp_millis:
type: integer
format: int64
description: Timestamp when the version was created, in milliseconds since epoch (Unix time)
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value pairs of metadata
CommitTableOperation:
type: object
description: 'A single operation within a batch commit.
Provide exactly one of the operation fields to specify the operation kind.
'
properties:
declare_table:
$ref: '#/components/schemas/DeclareTableRequest'
description: Declare (reserve) a new table in the namespace
create_table_version:
$ref: '#/components/schemas/CreateTableVersionRequest'
description: Create a new version entry for a table
delete_table_versions:
$ref: '#/components/schemas/BatchDeleteTableVersionsRequest'
description: Delete version ranges from a table
deregister_table:
$ref: '#/components/schemas/DeregisterTableRequest'
description: Deregister (soft-delete) a table
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>`).
'
BatchCommitTablesRequest:
type: object
description: 'Request to atomically commit a batch of table operations.
This replaces `BatchCreateTableVersionsRequest` with a more general interface
that supports mixed operations (DeclareTable, CreateTableVersion,
DeleteTableVersions, DeregisterTable)
within a single atomic transaction at the metadata layer.
All operations are committed atomically: either all succeed or none are applied.
'
required:
- operations
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
operations:
type: array
items:
$ref: '#/components/schemas/CommitTableOperation'
description: 'List of operations to commit atomically.
Supported operation types: DeclareTable, CreateTableVersion,
DeleteTableVersions, DeregisterTable.
'
BatchDeleteTableVersionsRequest:
type: object
description: 'Request to delete table version records.
Supports deleting ranges of versions for efficient bulk cleanup.
'
required:
- ranges
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
description: The table identifier
ranges:
type: array
items:
$ref: '#/components/schemas/VersionRange'
description: 'List of version ranges to delete.
Each range specifies start (inclusive) and end (exclusive) versions.
'
DeregisterTableRequest:
type: object
description: 'The table content remains available in the storage.
'
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
SetPropertyMode:
type: string
description: 'The behavior if the property key already exists.
Case insensitive, supports both PascalCase and snake_case. Valid values are:
- Overwrite (default): overwrite the existing value with the provided value
- Fail: fail the entire operation
- Skip: keep the existing value and skip setting the provided value
'
BatchCommitTablesResponse:
type: object
description: 'Response for a batch commit of table operations.
Contains the results of each operation in the same order as the request.
'
required:
- results
properties:
transaction_id:
type: string
description: Optional transaction identifier for the batch commit
results:
type: array
items:
$ref: '#/components/schemas/CommitTableResult'
description: 'Results for each operation, in the same order as the request operations.
Each result contains the outcome of the corresponding operation.
'
UnsetPropertyMode:
type: string
description: 'The behavior if the property key to unset does not exist.
Case insensitive, supports both PascalCase and snake_case. Valid values are:
- Skip (default): skip the property to unset
- Fail: fail the entire operation
'
CreateTableVersionResponse:
type: object
description: Response for creating a table version
properties:
transaction_id:
type: string
description: Optional transaction identifier
version:
$ref: '#/components/schemas/TableVersion'
AlterTransactionUnsetProperty:
type: object
properties:
key:
type: string
mode:
$ref: '#/components/schemas/UnsetPropertyMode'
CommitTableResult:
type: object
description: 'Result of a single operation within a batch commit.
Each result corresponds to one operation in the request, in the same order.
Exactly one of the result fields will be set.
'
properties:
declare_table:
$ref: '#/components/schemas/DeclareTableResponse'
description: Result of a DeclareTable operation
create_table_version:
$ref: '#/components/schemas/CreateTableVersionResponse'
description: Result of a CreateTableVersion operation
delete_table_versions:
$ref: '#/components/schemas/BatchDeleteTableVersionsResponse'
description: Result of a DeleteTableVersions operation
deregister_table:
$ref: '#/components/schemas/DeregisterTableResponse'
description: Result of a DeregisterTable operation
VersionRange:
type: object
description: 'A range of versions to delete (start inclusive, end exclusive).
Special values:
- `start_version: 0` with `end_version: -1` means ALL versions
'
required:
- start_version
- end_version
properties:
start_version:
type: integer
format: int64
description: 'Start version of the range (inclusive).
Use 0 to start from the first version.
'
end_version:
type: integer
format: int64
description: 'End version of the range (exclusive).
Use -1 to indicate all versions up to and including the latest.
'
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
TransactionStatus:
type: string
description: 'The status of a transaction.
Case insensitive, supports both PascalCase and snake_case. Valid values are:
- Queued: the transaction is queued and not yet started
- Running: the transaction is currently running
- Succeeded: the transaction has completed successfully
- Failed: the transaction has failed
- Canceled: the transaction was canceled
'
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
CreateTableVersionRequest:
type: object
description: 'Request to create a new table version entry.
This supports `put_if_not_exists` semantics,
where the operation fails if the version already exists.
'
required:
- version
- manifest_path
properties:
identity:
$ref: '#/components/schemas/Identity'
context:
$ref: '#/components/schemas/Context'
id:
type: array
items:
type: string
description: The table identifier
version:
type: integer
format: int64
minimum: 0
description: Version number to create
manifest_path:
type: string
description: Path to the manifest file for this version
manifest_size:
type: integer
format: int64
minimum: 0
description: Size of the manifest file in bytes
e_tag:
type: string
description: Optional ETag for the manifest file
metadata:
type: object
additionalProperties:
type: string
description: Optional metadata for the version
naming_scheme:
$ref: '#/components/schemas/ManifestNamingScheme'
AlterTransactionSetProperty:
type: object
properties:
key:
type: string
value:
type: string
mode:
$ref: '#/components/schemas/SetPropertyMode'
AlterTransactionResponse:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/TransactionStatus'
properties:
type: object
additionalProperties:
type: string
AlterTransactionSetStatus:
type: object
properties:
status:
$ref: '#/components/schemas/TransactionStatus'
DeregisterTableResponse:
type: object
properties:
transaction_id:
type: string
description: Optional transaction identifier
id:
type: array
items:
type: string
location:
type: string
properties:
type: object
description: 'If the implementation does not support table properties, it should return null for this field. Otherwise it should return the properties.
'
additionalProperties:
type: string
example:
owner: Ralph
created_at: '1452120468'
default: {}
nullable: true
responses:
AlterTransactionResponse:
description: Response of AlterTransaction
content:
application/json:
schema:
$ref: '#/components/schemas/AlterTransactionResponse'
DescribeTransactionResponse:
description: Response of DescribeTransaction
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeTransactionResponse'
BatchCommitTablesResponse:
description: Result of atomically committing a batch of mixed table operations
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCommitTablesResponse'
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
ConflictErrorResponse:
description: The request conflicts with the current state of the target resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/conflict
title: The namespace has been concurrently modified
status: 409
detail: ''
instance: /v1/namespaces/{ns}
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}
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