> ## Documentation Index > Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt > Use this file to discover all available pages before exploring further. # Atomically commit a batch of mixed table operations > 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. ## OpenAPI ````yaml /api-reference/rest/openapi.yml post /v1/table/batch-commit openapi: 3.1.1 info: title: Lance Namespace Specification 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: Namespace description: | Operations that are related to a namespace - name: Table description: | Operations that are related to a table - name: Index description: | Operations that are related to an index - name: Tag description: | Operations that are related to tags - name: Transaction description: | Operations that are related to a transaction - name: Metadata description: > Operations that only interact with object metadata and should be computationally lightweight - name: Data description: > Operations that interact with object data and might be computationally intensive paths: /v1/table/batch-commit: parameters: - $ref: '#/components/parameters/delimiter' post: tags: - Table - Metadata - Transaction summary: Atomically commit a batch of mixed table operations 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. operationId: BatchCommitTables 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' components: parameters: 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 schemas: 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. 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 `). 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-: `. For example, a context entry `{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`. additionalProperties: type: string 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 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. 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. Error codes: 0 - Unsupported: Operation not supported by this backend 1 - NamespaceNotFound: The specified namespace does not exist 2 - NamespaceAlreadyExists: A namespace with this name already exists 3 - NamespaceNotEmpty: Namespace contains tables or child namespaces 4 - TableNotFound: The specified table does not exist 5 - TableAlreadyExists: A table with this name already exists 6 - TableIndexNotFound: The specified table index does not exist 7 - TableIndexAlreadyExists: A table index with this name already exists 8 - TableTagNotFound: The specified table tag does not exist 9 - TableTagAlreadyExists: A table tag with this name already exists 10 - TransactionNotFound: The specified transaction does not exist 11 - TableVersionNotFound: The specified table version does not exist 12 - TableColumnNotFound: The specified table column does not exist 13 - InvalidInput: Malformed request or invalid parameters 14 - ConcurrentModification: Optimistic concurrency conflict 15 - PermissionDenied: User lacks permission for this operation 16 - Unauthenticated: Authentication credentials are missing or invalid 17 - ServiceUnavailable: Service is temporarily unavailable 18 - Internal: Unexpected server/implementation error 19 - InvalidTableState: Table is in an invalid state for the operation 20 - TableSchemaValidationError: Table schema validation failed 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 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 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' 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 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 ManifestNamingScheme: type: string description: > The naming scheme used for manifest files in the `_versions/` directory. Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions. example: V2 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. 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. CreateTableVersionResponse: type: object description: Response for creating a table version properties: transaction_id: type: string description: Optional transaction identifier version: $ref: '#/components/schemas/TableVersion' 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 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 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 responses: BatchCommitTablesResponse: description: Result of atomically committing a batch of mixed table operations content: application/json: schema: $ref: '#/components/schemas/BatchCommitTablesResponse' 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 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 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 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} 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 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 securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: /oauth/token scopes: {} BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: x-api-key ````