# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
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: ""

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

security:
  - OAuth2: []
  - BearerAuth: []
  - ApiKeyAuth: []

paths:
  # Namespace APIs

  /v1/namespace/{id}/create:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Namespace
        - Metadata
      summary: Create a new namespace
      operationId: CreateNamespace
      description: |
        Create new namespace `id`.

        During the creation process, the implementation may modify user-provided `properties`,
        such as adding additional properties like `created_at` to user-provided properties,
        omitting any specific property, or performing actions based on any property value.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateNamespaceRequest"
      responses:
        200:
          $ref: "#/components/responses/CreateNamespaceResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        403:
          $ref: "#/components/responses/ForbiddenErrorResponse"
        404:
          $ref: "#/components/responses/NotFoundErrorResponse"
        406:
          $ref: "#/components/responses/UnsupportedOperationErrorResponse"
        409:
          $ref: "#/components/responses/ConflictErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
        5XX:
          $ref: "#/components/responses/ServerErrorResponse"

  /v1/namespace/{id}/list:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - $ref: "#/components/parameters/page_token"
      - $ref: "#/components/parameters/limit"
    get:
      tags:
        - Namespace
        - Metadata
      summary: List namespaces
      operationId: ListNamespaces
      description: |
        List all child namespace names of the parent namespace `id`.

        REST NAMESPACE ONLY
        REST namespace uses GET to perform this operation without a request body.
        It passes in the `ListNamespacesRequest` information in the following way:
        - `id`: pass through path parameter of the same name
        - `page_token`: pass through query parameter of the same name
        - `limit`: pass through query parameter of the same name
      responses:
        200:
          $ref: "#/components/responses/ListNamespacesResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        403:
          $ref: "#/components/responses/ForbiddenErrorResponse"
        404:
          $ref: "#/components/responses/NotFoundErrorResponse"
        406:
          $ref: "#/components/responses/UnsupportedOperationErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
        5XX:
          $ref: "#/components/responses/ServerErrorResponse"

  /v1/namespace/{id}/describe:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Namespace
        - Metadata
      summary: Describe a namespace
      operationId: DescribeNamespace
      description: |
        Describe the detailed information for namespace `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescribeNamespaceRequest"
      responses:
        200:
          $ref: "#/components/responses/DescribeNamespaceResponse"
        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/namespace/{id}/drop:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Namespace
        - Metadata
      summary: Drop a namespace
      operationId: DropNamespace
      description: |
        Drop namespace `id` from its parent namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DropNamespaceRequest"
      responses:
        200:
          $ref: "#/components/responses/DropNamespaceResponse"
        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/namespace/{id}/exists:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Namespace
        - Metadata
      summary: Check if a namespace exists
      operationId: NamespaceExists
      description: |
        Check if namespace `id` exists.

        This operation must behave exactly like the DescribeNamespace API,
        except it does not contain a response body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NamespaceExistsRequest"
      responses:
        200:
          description: Success, no content
        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/namespace/{id}/table/list:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - $ref: "#/components/parameters/page_token"
      - $ref: "#/components/parameters/limit"
    get:
      tags:
        - Namespace
        - Table
        - Metadata
      summary: List tables in a namespace
      operationId: ListTables
      description: |
        List all child table names of the parent namespace `id`.

        REST NAMESPACE ONLY
        REST namespace uses GET to perform this operation without a request body.
        It passes in the `ListTablesRequest` information in the following way:
        - `id`: pass through path parameter of the same name
        - `page_token`: pass through query parameter of the same name
        - `limit`: pass through query parameter of the same name
      responses:
        200:
          $ref: "#/components/responses/ListTablesResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        403:
          $ref: "#/components/responses/ForbiddenErrorResponse"
        404:
          $ref: "#/components/responses/NotFoundErrorResponse"
        406:
          $ref: "#/components/responses/UnsupportedOperationErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
        5XX:
          $ref: "#/components/responses/ServerErrorResponse"

  # Table Metadata APIs

  /v1/table:
    get:
      tags:
        - Table
      summary: List all tables
      operationId: ListAllTables
      description: |
        List all tables across all namespaces.

        REST NAMESPACE ONLY
        REST namespace uses GET to perform this operation without a request body.
        It passes in the `ListAllTablesRequest` information in the following way:
        - `page_token`: pass through query parameter of the same name
        - `limit`: pass through query parameter of the same name
        - `delimiter`: pass through query parameter of the same name
      parameters:
        - $ref: "#/components/parameters/delimiter"
        - $ref: "#/components/parameters/page_token"
        - $ref: "#/components/parameters/limit"
      responses:
        200:
          $ref: "#/components/responses/ListTablesResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        403:
          $ref: "#/components/responses/ForbiddenErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
        5XX:
          $ref: "#/components/responses/ServerErrorResponse"

  /v1/table/{id}/register:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Register a table to a namespace
      operationId: RegisterTable
      description: |
        Register an existing table at a given storage location as `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterTableRequest"
      responses:
        200:
          $ref: "#/components/responses/RegisterTableResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        403:
          $ref: "#/components/responses/ForbiddenErrorResponse"
        404:
          $ref: "#/components/responses/NotFoundErrorResponse"
        406:
          $ref: "#/components/responses/UnsupportedOperationErrorResponse"
        409:
          $ref: "#/components/responses/ConflictErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
        5XX:
          $ref: "#/components/responses/ServerErrorResponse"

  /v1/table/{id}/describe:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - $ref: "#/components/parameters/with_table_uri"
      - $ref: "#/components/parameters/load_detailed_metadata"
    post:
      tags:
        - Table
        - Metadata
      summary: Describe information of a table
      operationId: DescribeTable
      description: |
        Describe the detailed information for table `id`.

        REST NAMESPACE ONLY
        REST namespace passes `with_table_uri` and `load_detailed_metadata` as query parameters instead of in the request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescribeTableRequest"
      responses:
        200:
          $ref: "#/components/responses/DescribeTableResponse"
        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}/exists:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Check if a table exists
      operationId: TableExists
      description: |
        Check if table `id` exists.

        This operation should behave exactly like DescribeTable,
        except it does not contain a response body.

        For DirectoryNamespace implementation, a table exists if either:
        - The table has Lance data versions (regular table created with CreateTable)
        - A `.lance-reserved` file exists in the table directory (declared table created with DeclareTable)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TableExistsRequest"
      responses:
        200:
          description: Success, no content
        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}/drop:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Drop a table
      operationId: DropTable
      description: |
        Drop table `id` and delete its data.

        REST NAMESPACE ONLY
        REST namespace does not use a request body for this operation.
        The `DropTableRequest` information is passed in the following way:
        - `id`: pass through path parameter of the same name
      responses:
        200:
          $ref: "#/components/responses/DropTableResponse"
        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}/deregister:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Deregister a table
      operationId: DeregisterTable
      description: |
        Deregister table `id` from its namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeregisterTableRequest"
      responses:
        200:
          $ref: "#/components/responses/DeregisterTableResponse"
        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}/restore:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Restore table to a specific version
      operationId: RestoreTable
      description: |
        Restore table `id` to a specific version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestoreTableRequest"
      responses:
        200:
          $ref: "#/components/responses/RestoreTableResponse"
        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}/rename:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Rename a table
      operationId: RenameTable
      description: |
        Rename table `id` to a new name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenameTableRequest"
      responses:
        200:
          $ref: "#/components/responses/RenameTableResponse"
        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/table/{id}/schema_metadata/update:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Update table schema metadata
      operationId: UpdateTableSchemaMetadata
      description: |
        Replace the schema metadata for table `id` with the provided key-value pairs.

        REST NAMESPACE ONLY
        REST namespace uses a direct object (map of string to string) as both request and response body
        instead of the wrapped `UpdateTableSchemaMetadataRequest` and `UpdateTableSchemaMetadataResponse`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              description: Schema metadata key-value pairs
      responses:
        200:
          description: Schema metadata update result
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                description: The updated schema metadata
        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}/version/list:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - $ref: "#/components/parameters/page_token"
      - $ref: "#/components/parameters/limit"
      - name: descending
        in: query
        description: |
          When true, versions are guaranteed to be returned in descending order (latest to oldest).
          When false or not specified, the ordering is implementation-defined.
        required: false
        schema:
          type: boolean
    post:
      tags:
        - Table
        - Metadata
      summary: List all versions of a table
      operationId: ListTableVersions
      description: |
        List all versions (commits) of table `id` with their metadata.

        Use `descending=true` to guarantee versions are returned in descending order (latest to oldest).
        Otherwise, the ordering is implementation-defined.

        REST NAMESPACE ONLY
        REST namespace does not use a request body for this operation.
        The `ListTableVersionsRequest` information is passed in the following way:
        - `id`: pass through path parameter of the same name
        - `page_token`: pass through query parameter of the same name
        - `limit`: pass through query parameter of the same name
        - `descending`: pass through query parameter of the same name
      responses:
        200:
          $ref: "#/components/responses/ListTableVersionsResponse"
        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}/version/create:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Create a new table version
      operationId: CreateTableVersion
      description: |
        Create a new version entry for table `id`.

        This operation supports `put_if_not_exists` semantics.
        The operation will fail with 409 Conflict if the version already exists.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTableVersionRequest"
      responses:
        200:
          $ref: "#/components/responses/CreateTableVersionResponse"
        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/table/{id}/version/describe:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Describe a specific table version
      operationId: DescribeTableVersion
      description: |
        Describe the detailed information for a specific version of table `id`.

        Returns the manifest path and metadata for the specified version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescribeTableVersionRequest"
      responses:
        200:
          $ref: "#/components/responses/DescribeTableVersionResponse"
        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}/version/delete:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Delete table version records
      operationId: BatchDeleteTableVersions
      description: |
        Delete version metadata records for table `id`.

        This operation deletes version tracking records, NOT the actual table data.
        It supports deleting ranges of versions for efficient bulk cleanup.

        Special range values:
        - `start_version: 0` with `end_version: -1` means delete ALL version records
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchDeleteTableVersionsRequest"
      responses:
        200:
          $ref: "#/components/responses/BatchDeleteTableVersionsResponse"
        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/version/batch-create:
    parameters:
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Atomically create versions for multiple tables
      operationId: BatchCreateTableVersions
      description: |
        Atomically create new version entries for multiple tables.

        This operation is atomic: either all table versions are created successfully,
        or none are created. If any version creation fails (e.g., due to conflict),
        the entire batch operation fails.

        Each entry in the request specifies the table identifier and version details.
        This supports `put_if_not_exists` semantics for each version entry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchCreateTableVersionsRequest"
      responses:
        200:
          $ref: "#/components/responses/BatchCreateTableVersionsResponse"
        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/table/batch-commit:
    parameters:
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
        - 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/table/{id}/alter_columns:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Modify existing columns
      operationId: AlterTableAlterColumns
      description: |
        Modify existing columns in table `id`, such as renaming or changing data types.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlterTableAlterColumnsRequest"
      responses:
        200:
          $ref: "#/components/responses/AlterTableAlterColumnsResponse"
        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}/drop_columns:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Remove columns from table
      operationId: AlterTableDropColumns
      description: |
        Remove specified columns from table `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlterTableDropColumnsRequest"
      responses:
        200:
          $ref: "#/components/responses/AlterTableDropColumnsResponse"
        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}/stats:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Get table statistics
      operationId: GetTableStats
      description: |
        Get statistics for table `id`, including row counts, data sizes, and column statistics.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetTableStatsRequest"
      responses:
        200:
          $ref: "#/components/responses/GetTableStatsResponse"
        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"

  # Table Data APIs

  /v1/table/{id}/insert:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - name: mode
        in: query
        description: |
          How the insert should behave. Case insensitive, supports both PascalCase and snake_case. Valid values are:
          - Append (default): insert data to the existing table
          - Overwrite: remove all data in the table and then insert data to it
        required: false
        schema:
          type: string
          default: append
    post:
      tags:
        - Table
        - Data
      summary: Insert records into a table
      operationId: InsertIntoTable
      description: |
        Insert new records into table `id`.

        For tables that have been declared but not yet created on storage
        (is_only_declared=true), this operation will create the table with
        the provided data.

        REST NAMESPACE ONLY
        REST namespace uses Arrow IPC stream as the request body.
        It passes in the `InsertIntoTableRequest` information in the following way:
        - `id`: pass through path parameter of the same name
        - `mode`: pass through query parameter of the same name
      requestBody:
        description: Arrow IPC stream containing the records to insert
        content:
          application/vnd.apache.arrow.stream:
            schema:
              type: string
              format: binary
        required: true
      responses:
        200:
          $ref: "#/components/responses/InsertIntoTableResponse"
        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}/merge_insert:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - name: "on"
        in: query
        description: Column name to use for matching rows (required)
        required: true
        schema:
          type: string
      - name: "when_matched_update_all"
        in: query
        description: Update all columns when rows match
        required: false
        schema:
          type: boolean
          default: false
      - name: "when_matched_update_all_filt"
        in: query
        description: The row is updated (similar to UpdateAll) only for rows where the SQL expression evaluates to true
        required: false
        schema:
          type: string
      - name: "when_not_matched_insert_all"
        in: query
        description: Insert all columns when rows don't match
        required: false
        schema:
          type: boolean
          default: false
      - name: "when_not_matched_by_source_delete"
        in: query
        description: Delete all rows from target table that don't match a row in the source table
        required: false
        schema:
          type: boolean
          default: false
      - name: "when_not_matched_by_source_delete_filt"
        in: query
        description: Delete rows from the target table if there is no match AND the SQL expression evaluates to true
        schema:
          type: string
      - name: "timeout"
        in: query
        description: Timeout for the operation (e.g., "30s", "5m")
        required: false
        schema:
          type: string
      - name: "use_index"
        in: query
        description: Whether to use index for matching rows
        required: false
        schema:
          type: boolean
          default: false
    post:
      tags:
        - Table
        - Data
      summary: Merge insert (upsert) records into a table
      operationId: MergeInsertIntoTable
      description: |
        Performs a merge insert (upsert) operation on table `id`.
        This operation updates existing rows
        based on a matching column and inserts new rows that don't match.
        It returns the number of rows inserted and updated.

        For tables that have been declared but not yet created on storage
        (is_only_declared=true), this operation will create the table with
        the provided data (since there are no existing rows to merge with).

        REST NAMESPACE ONLY
        REST namespace uses Arrow IPC stream as the request body.
        It passes in the `MergeInsertIntoTableRequest` information in the following way:
        - `id`: pass through path parameter of the same name
        - `on`: pass through query parameter of the same name
        - `when_matched_update_all`: pass through query parameter of the same name
        - `when_matched_update_all_filt`: pass through query parameter of the same name
        - `when_not_matched_insert_all`: pass through query parameter of the same name
        - `when_not_matched_by_source_delete`: pass through query parameter of the same name
        - `when_not_matched_by_source_delete_filt`: pass through query parameter of the same name
      requestBody:
        description: Arrow IPC stream containing the records to merge
        content:
          application/vnd.apache.arrow.stream:
            schema:
              type: string
              format: binary
        required: true
      responses:
        200:
          $ref: "#/components/responses/MergeInsertIntoTableResponse"
        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}/update:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Update rows in a table
      operationId: UpdateTable
      description: |
        Update existing rows in table `id`.
      requestBody:
        description: Update request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTableRequest"
        required: true
      responses:
        200:
          $ref: "#/components/responses/UpdateTableResponse"
        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}/delete:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Delete rows from a table
      operationId: DeleteFromTable
      description: |
        Delete rows from table `id`.
      requestBody:
        description: Delete request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteFromTableRequest"
        required: true
      responses:
        200:
          $ref: "#/components/responses/DeleteFromTableResponse"
        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}/query:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Query a table
      operationId: QueryTable
      description: |
        Query table `id` with vector search, full text search and optional SQL filtering.
        Returns results in Arrow IPC file or stream format.

        REST NAMESPACE ONLY
        REST namespace returns the response as Arrow IPC file binary data
        instead of the `QueryTableResponse` JSON object.
      requestBody:
        description: Query request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryTableRequest"
        required: true
      responses:
        200:
          $ref: "#/components/responses/QueryTableResponse"
        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}/count_rows:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Count rows in a table
      operationId: CountTableRows
      description: |
        Count the number of rows in table `id`

        REST NAMESPACE ONLY
        REST namespace returns the response as a plain integer
        instead of the `CountTableRowsResponse` JSON object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CountTableRowsRequest"
      responses:
        200:
          $ref: "#/components/responses/CountTableRowsResponse"
        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:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - name: "mode"
        in: query
        required: false
        schema:
          type: string
    post:
      tags:
        - Table
        - Data
      summary: Create a table with the given name
      operationId: CreateTable
      description: |
        Create table `id` in the namespace with the given data in Arrow IPC stream.

        The schema of the Arrow IPC stream is used as the table schema.
        If the stream is empty, the API creates a new empty table.

        REST NAMESPACE ONLY
        REST namespace uses Arrow IPC stream as the request body.
        It passes in the `CreateTableRequest` information in the following way:
        - `id`: pass through path parameter of the same name
        - `mode`: pass through query parameter of the same name
      requestBody:
        description: Arrow IPC data
        content:
          application/vnd.apache.arrow.stream:
            schema:
              type: string
              format: binary
        required: true
      responses:
        200:
          $ref: "#/components/responses/CreateTableResponse"
        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}/explain_plan:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Get query execution plan explanation
      operationId: ExplainTableQueryPlan
      description: |
        Get the query execution plan for a query against table `id`.
        Returns a human-readable explanation of how the query will be executed.

        REST NAMESPACE ONLY
        REST namespace returns the response as a plain string
        instead of the `ExplainTableQueryPlanResponse` JSON object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExplainTableQueryPlanRequest"
      responses:
        200:
          $ref: "#/components/responses/ExplainTableQueryPlanResponse"
        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}/analyze_plan:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Analyze query execution plan
      operationId: AnalyzeTableQueryPlan
      description: |
        Analyze the query execution plan for a query against table `id`.
        Returns detailed statistics and analysis of the query execution plan.

        REST NAMESPACE ONLY
        REST namespace returns the response as a plain string
        instead of the `AnalyzeTableQueryPlanResponse` JSON object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyzeTableQueryPlanRequest"
      responses:
        200:
          $ref: "#/components/responses/AnalyzeTableQueryPlanResponse"
        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}/add_columns:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Data
      summary: Add new columns to table schema
      operationId: AlterTableAddColumns
      description: |
        Add new columns to table `id` using SQL expressions or default values.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlterTableAddColumnsRequest"
      responses:
        200:
          $ref: "#/components/responses/AlterTableAddColumnsResponse"
        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"

  # Table Index APIs

  /v1/table/{id}/create_index:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Index
        - Metadata
      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_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:
        - Table
        - Index
        - Metadata
      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:
        - Table
        - Index
        - Metadata
      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:
        - Table
        - Index
        - Metadata
      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:
        - Table
        - Index
        - Metadata
      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"

  # Table Tag APIs

  /v1/table/{id}/tags/list:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
      - $ref: "#/components/parameters/page_token"
      - $ref: "#/components/parameters/limit"
    post:
      tags:
        - Table
        - Tag
        - Metadata
      summary: List all tags for a table
      operationId: ListTableTags
      description: |
        List all tags that have been created for table `id`.
        Returns a map of tag names to their corresponding version numbers and metadata.

        REST NAMESPACE ONLY
        REST namespace does not use a request body for this operation.
        The `ListTableTagsRequest` information is passed in the following way:
        - `id`: pass through path parameter of the same name
        - `page_token`: pass through query parameter of the same name
        - `limit`: pass through query parameter of the same name
      responses:
        200:
          $ref: "#/components/responses/ListTableTagsResponse"
        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}/tags/version:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Tag
        - Metadata
      summary: Get version for a specific tag
      operationId: GetTableTagVersion
      description: |
        Get the version number that a specific tag points to for table `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetTableTagVersionRequest"
      responses:
        200:
          $ref: "#/components/responses/GetTableTagVersionResponse"
        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}/declare:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Declare a table
      operationId: DeclareTable
      description: |
        Declare a table with the given name without touching storage.
        This is a metadata-only operation that records the table existence and sets up aspects like access control.

        For DirectoryNamespace implementation, this creates a `.lance-reserved` file in the table directory
        to mark the table's existence without creating actual Lance data files.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeclareTableRequest"
      responses:
        200:
          $ref: "#/components/responses/DeclareTableResponse"
        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/table/{id}/create-empty:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Metadata
      summary: Create an empty table
      operationId: CreateEmptyTable
      deprecated: true
      description: |
        Create an empty table with the given name without touching storage.
        This is a metadata-only operation that records the table existence and sets up aspects like access control.

        For DirectoryNamespace implementation, this creates a `.lance-reserved` file in the table directory
        to mark the table's existence without creating actual Lance data files.

        **Deprecated**: Use `DeclareTable` instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEmptyTableRequest"
      responses:
        200:
          $ref: "#/components/responses/CreateEmptyTableResponse"
        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/table/{id}/tags/create:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Tag
        - Metadata
      summary: Create a new tag
      operationId: CreateTableTag
      description: |
        Create a new tag for table `id` that points to a specific version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTableTagRequest"
      responses:
        200:
          $ref: "#/components/responses/CreateTableTagResponse"
        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/table/{id}/tags/delete:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Tag
        - Metadata
      summary: Delete a tag
      operationId: DeleteTableTag
      description: |
        Delete an existing tag from table `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteTableTagRequest"
      responses:
        200:
          $ref: "#/components/responses/DeleteTableTagResponse"
        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}/tags/update:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Table
        - Tag
        - Metadata
      summary: Update a tag to point to a different version
      operationId: UpdateTableTag
      description: |
        Update an existing tag for table `id` to point to a different version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTableTagRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdateTableTagResponse"
        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"

  # Transaction API

  /v1/transaction/{id}/describe:
    parameters:
      - $ref: "#/components/parameters/id"
      - $ref: "#/components/parameters/delimiter"
    post:
      tags:
        - Transaction
        - Metadata
      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
        - Metadata
      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:
  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
    page_token:
      name: page_token
      description: Pagination token from a previous request
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/PageToken"
    limit:
      name: limit
      description: Maximum number of items to return
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/PageLimit"
    with_table_uri:
      name: with_table_uri
      description: Whether to include the table URI in the response
      in: query
      required: false
      schema:
        type: boolean
        default: false
    load_detailed_metadata:
      name: load_detailed_metadata
      description: |
        Whether to load detailed metadata that requires opening the dataset.
        When false (default), only `location` is required in the response.
        When true, the response includes additional metadata such as `version`, `schema`, and `stats`.
      in: query
      required: false
      schema:
        type: boolean
        default: false

  schemas:
    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

    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>`).

    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

    CreateNamespaceRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        mode:
          type: string
          description: |
            There are three modes when trying to create a namespace,
            to differentiate the behavior when a namespace of the same name already exists.
            Case insensitive, supports both PascalCase and snake_case. Valid values are:
              * Create: the operation fails with 409.
              * ExistOk: the operation succeeds and the existing namespace is kept.
              * Overwrite: the existing namespace is dropped and a new empty namespace with this name is created.
        properties:
          type: object
          description: |
            Properties stored on the namespace, if supported by the implementation.
          additionalProperties:
            type: string

    CreateNamespaceResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        properties:
          description: |
            Properties after the namespace is created.

            If the server does not support namespace properties, it should return null for this field.
            If namespace properties are supported, but none are set, it should return an empty object.
          type: object
          additionalProperties:
            type: string

    ListNamespacesRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        page_token:
          $ref: "#/components/schemas/PageToken"
        limit:
          $ref: "#/components/schemas/PageLimit"

    ListNamespacesResponse:
      type: object
      required:
        - namespaces
      properties:
        namespaces:
          type: array
          uniqueItems: true
          description: |
            The list of names of the child namespaces relative to the parent namespace `id` in the request.
          items:
            type: string
        page_token:
          $ref: "#/components/schemas/PageToken"

    DescribeNamespaceRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string

    DescribeNamespaceResponse:
      type: object
      properties:
        properties:
          type: object
          description:
            Properties stored on the namespace, if supported by the server.
            If the server does not support namespace properties, it should return null for this field.
            If namespace properties are supported, but none are set, it should return an empty object.
          additionalProperties:
            type: string
          example: { "owner": "Ralph", "created_at": "1452120468" }
          default: {}
          nullable: true

    DropNamespaceRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        mode:
          type: string
          description: |
            The mode for dropping a namespace, deciding the server behavior when the namespace to drop is not found.
            Case insensitive, supports both PascalCase and snake_case. Valid values are:
            - Fail (default): the server must return 400 indicating the namespace to drop does not exist.
            - Skip: the server must return 204 indicating the drop operation has succeeded.
        behavior:
          type: string
          description: |
            The behavior for dropping a namespace.
            Case insensitive, supports both PascalCase and snake_case. Valid values are:
            - Restrict (default): the namespace should not contain any table or child namespace when drop is initiated.
                If tables are found, the server should return error and not drop the namespace.
            - Cascade: all tables and child namespaces in the namespace are dropped before the namespace is dropped.

    DropNamespaceResponse:
      type: object
      properties:
        properties:
          type: object
          description: |
            If the implementation does not support namespace properties, it should return null for this field. Otherwise it should return the properties.
          additionalProperties:
            type: string
        transaction_id:
          description: |
            If present, indicating the operation is long running and should be tracked using DescribeTransaction
          type: array
          items:
            type: string

    NamespaceExistsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string

    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

    PageLimit:
      description: |
        An inclusive upper bound of the
        number of results that a caller will receive.
      type: integer
      nullable: true

    RegisterTableRequest:
      type: object
      required:
        - location
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        location:
          type: string
        mode:
          type: string
          description: |
            There are two modes when trying to register a table,
            to differentiate the behavior when a table of the same name already exists.
            Case insensitive, supports both PascalCase and snake_case. Valid values are:
              * Create (default): the operation fails with 409.
              * Overwrite: the existing table registration is replaced with the new registration.
        properties:
          type: object
          description: |
            Properties stored on the table, if supported by the implementation.
          additionalProperties:
            type: string

    RegisterTableResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        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

    ListTablesRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        page_token:
          $ref: "#/components/schemas/PageToken"
        limit:
          $ref: "#/components/schemas/PageLimit"
        include_declared:
          type: boolean
          description: |
            When true, includes tables that have been declared in the namespace
            but not yet created on storage, in addition to tables that have
            been created. When false or not set, only tables with storage
            components are returned.

    ListTablesResponse:
      type: object
      required:
        - tables
      properties:
        tables:
          type: array
          uniqueItems: true
          description: |
            The list of names of all the tables under the connected namespace implementation.
            This should recursively list all the tables in all child namespaces.
            Each string in the list is the full identifier in string form.
          items:
            type: string
        page_token:
          $ref: "#/components/schemas/PageToken"

    DescribeTableRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        version:
          description: |
            Version of the table to describe.
            If not specified, server should resolve it to the latest version.
          type: integer
          format: int64
          minimum: 0
        with_table_uri:
          description: |
            Whether to include the table URI in the response.
            Default is false.
          type: boolean
          default: false
        load_detailed_metadata:
          description: |
            Whether to load detailed metadata that requires opening the dataset.
            When true, the response must include all detailed metadata such as `version`, `schema`, and `stats`
            which require reading the dataset.
            When not set, the implementation can decide whether to return detailed metadata
            and which parts of detailed metadata to return.
          type: boolean
        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

    DescribeTableResponse:
      type: object
      properties:
        table:
          type: string
          description: |
            Table name.
            Only populated when `load_detailed_metadata` is true.
        namespace:
          type: array
          items:
            type: string
          description: |
            The namespace identifier as a list of parts.
            Only populated when `load_detailed_metadata` is true.
        version:
          type: integer
          format: int64
          minimum: 0
          description: |
            Table version number.
            Only populated when `load_detailed_metadata` is true.
        location:
          type: string
          description: |
            Table storage location (e.g., S3/GCS path).
        table_uri:
          type: string
          description: |
            Table URI. Unlike location, this field must be a complete and valid URI.
            Only returned when `with_table_uri` is true.
        schema:
          $ref: "#/components/schemas/JsonArrowSchema"
          description: |
            Table schema in JSON Arrow format.
            Only populated when `load_detailed_metadata` is true.
        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.
            When `vend_credentials` is true, this field may include vended credentials.
            If the vended credentials are temporary, the `expires_at_millis` key should be
            included to indicate the millisecond timestamp when the credentials expire.
          additionalProperties:
            type: string
        stats:
          $ref: "#/components/schemas/TableBasicStats"
          nullable: true
          description: |
            Table statistics.
            Only populated when `load_detailed_metadata` is true.
        metadata:
          type: object
          description: |
            Optional table metadata as key-value pairs. This records the information of the table
            and requires loading the table.
            It is only populated when `load_detailed_metadata` is true.
          additionalProperties:
            type: string
        properties:
          type: object
          description:
            Properties stored on the table, if supported by the server. This records the
            information managed by the namespace.
            If the server does not support table properties, it should return null for this field.
            If table properties are supported, but none are set, it should return an empty object.
          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.
        is_only_declared:
          type: boolean
          description: |
            When true, indicates that the table has been declared in the namespace
            but not yet created on storage. This means the table exists in the
            namespace but has no data files on the underlying storage.
            Operations like describe_table with load_detailed_metadata=true may fail
            for such tables. When false or not set, the table has storage components
            (data and metadata files).

    TableBasicStats:
      type: object
      required:
        - num_deleted_rows
        - num_fragments
      properties:
        num_deleted_rows:
          type: integer
          minimum: 0
          description: Number of deleted rows in the table
        num_fragments:
          type: integer
          minimum: 0
          description: Number of fragments in the table

    CountTableRowsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        version:
          description: |
            Version of the table to describe.
            If not specified, server should resolve it to the latest version.
          type: integer
          format: int64
          minimum: 0
        predicate:
          description: |
            Optional SQL predicate to filter rows for counting
          type: string

    CountTableRowsResponse:
      type: integer
      format: int64
      description: |
        Response containing the count of rows.
        Serializes transparently as just the number for backward compatibility.
      minimum: 0

    InsertIntoTableRequest:
      type: object
      description: |
        Request for inserting records into a table, excluding the Arrow IPC stream.
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        mode:
          type: string
          description: |
            How the insert should behave. Case insensitive, supports both PascalCase and snake_case. Valid values are:
            - Append (default): insert data to the existing table
            - Overwrite: remove all data in the table and then insert data to it
          default: append

    InsertIntoTableResponse:
      type: object
      description: Response from inserting records into a table
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    MergeInsertIntoTableRequest:
      type: object
      description: |
        Request for merging or inserting records into a table, excluding the Arrow IPC stream.
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        "on":
          description: Column name to use for matching rows (required)
          type: string
        when_matched_update_all:
          description: Update all columns when rows match
          type: boolean
          default: false
        when_matched_update_all_filt:
          description: The row is updated (similar to UpdateAll) only for rows where the SQL expression evaluates to true
          type: string
        when_not_matched_insert_all:
          description: Insert all columns when rows don't match
          type: boolean
          default: false
        when_not_matched_by_source_delete:
          description: Delete all rows from target table that don't match a row in the source table
          type: boolean
          default: false
        when_not_matched_by_source_delete_filt:
          description: Delete rows from the target table if there is no match AND the SQL expression evaluates to true
          type: string
        timeout:
          description: Timeout for the operation (e.g., "30s", "5m")
          type: string
        use_index:
          description: Whether to use index for matching rows
          type: boolean
          default: false

    MergeInsertIntoTableResponse:
      type: object
      description: Response from merge insert operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        num_updated_rows:
          type: integer
          format: int64
          description: Number of rows updated
          minimum: 0
        num_inserted_rows:
          type: integer
          format: int64
          description: Number of rows inserted
          minimum: 0
        num_deleted_rows:
          type: integer
          format: int64
          description: Number of rows deleted (typically 0 for merge insert)
          minimum: 0
        version:
          type: integer
          format: int64
          description: The commit version associated with the operation
          minimum: 0

    UpdateTableRequest:
      type: object
      description: |
        Each update consists of a column name and an SQL expression that will be
        evaluated against the current row's value. Optionally, a predicate can be
        provided to filter which rows to update.
      required:
        - updates
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        predicate:
          type: string
          nullable: true
          description: Optional SQL predicate to filter rows for update
        updates:
          type: array
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: string
          description: List of column updates as [column_name, expression] pairs
        properties:
          type: object
          description: |
            Properties stored on the table, if supported by the implementation.
          additionalProperties:
            type: string

    UpdateTableResponse:
      type: object
      required:
        - updated_rows
        - version
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        updated_rows:
          type: integer
          format: int64
          description: Number of rows updated
          minimum: 0
        version:
          type: integer
          format: int64
          description: The commit version associated with the operation
          minimum: 0
        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

    DeleteFromTableRequest:
      type: object
      description: |
        Delete data from table based on a SQL predicate.
        Returns the number of rows that were deleted.
      required:
        - predicate
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
          description: The namespace identifier
        predicate:
          type: string
          description: SQL predicate to filter rows for deletion

    DeleteFromTableResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        version:
          type: integer
          format: int64
          description: The commit version associated with the operation
          minimum: 0

    QueryTableRequest:
      type: object
      required:
        - vector
        - k
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        bypass_vector_index:
          type: boolean
          description: Whether to bypass vector index
        columns:
          type: object
          nullable: true
          description: |
            Optional columns to return. Provide either column_names or column_aliases, not both.
          properties:
            column_names:
              type: array
              items:
                type: string
              description: List of column names to return
            column_aliases:
              type: object
              additionalProperties:
                type: string
              description: Object mapping output aliases to source column names
        distance_type:
          type: string
          description: Distance metric to use
        ef:
          type: integer
          minimum: 0
          description: Search effort parameter for HNSW index
        fast_search:
          type: boolean
          description: Whether to use fast search
        filter:
          type: string
          description: Optional SQL filter expression
        full_text_query:
          type: object
          nullable: true
          description: Optional full-text search query. Provide either string_query or structured_query, not both.
          properties:
            string_query:
              $ref: "#/components/schemas/StringFtsQuery"
            structured_query:
              $ref: "#/components/schemas/StructuredFtsQuery"
        k:
          type: integer
          minimum: 0
          description: Number of results to return
        lower_bound:
          type: number
          format: float
          description: Lower bound for search
        nprobes:
          type: integer
          minimum: 0
          description: Number of probes for IVF index
        offset:
          type: integer
          minimum: 0
          description: Number of results to skip
        prefilter:
          type: boolean
          description: Whether to apply filtering before vector search
        refine_factor:
          type: integer
          format: int32
          minimum: 0
          description: Refine factor for search
        upper_bound:
          type: number
          format: float
          description: Upper bound for search
        vector:
          type: object
          nullable: true
          description: Query vector(s) for similarity search. Provide either single_vector or multi_vector, not both.
          properties:
            single_vector:
              type: array
              items:
                type: number
                format: float
              description: Single query vector
            multi_vector:
              type: array
              items:
                type: array
                items:
                  type: number
                  format: float
              description: Multiple query vectors for batch search
        vector_column:
          type: string
          description: Name of the vector column to search
        version:
          type: integer
          format: int64
          minimum: 0
          description: Table version to query
        with_row_id:
          type: boolean
          description: If true, return the row id as a column called `_rowid`

    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_HNSW_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

    CreateTableIndexResponse:
      type: object
      description: Response for create index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    CreateTableScalarIndexResponse:
      type: object
      description: Response for create scalar index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    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"

    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"

    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

    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

    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

    JsonArrowSchema:
      type: object
      description: |
        JSON representation of a Apache Arrow schema.
      required:
        - fields
      properties:
        fields:
          type: array
          items:
            $ref: "#/components/schemas/JsonArrowField"
        metadata:
          type: object
          additionalProperties:
            type: string
          propertyNames:
            type: string

    JsonArrowField:
      type: object
      description: |
        JSON representation of an Apache Arrow field.
      required:
        - name
        - type
        - nullable
      properties:
        metadata:
          type: object
          additionalProperties:
            type: string
          propertyNames:
            type: string
        name:
          type: string
        nullable:
          type: boolean
        type:
          $ref: "#/components/schemas/JsonArrowDataType"
    JsonArrowDataType:
      type: object
      description: JSON representation of an Apache Arrow DataType
      required:
        - type
      properties:
        fields:
          type: array
          items:
            $ref: "#/components/schemas/JsonArrowField"
          description: Fields for complex types like Struct, Union, etc.
        length:
          type: integer
          format: int64
          description: Length for fixed-size types
          minimum: 0
        type:
          type: string
          description: The data type name

    Binary:
      type: string
      format: binary

    CreateTableRequest:
      type: object
      description: |
        Request for creating a table, excluding the Arrow IPC stream.
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        mode:
          type: string
          description: |
            There are three modes when trying to create a table,
            to differentiate the behavior when a table of the same name already exists.
            Case insensitive, supports both PascalCase and snake_case. Valid values are:
              * Create: the operation fails with 409.
              * ExistOk: the operation succeeds and the existing table is kept.
              * Overwrite: the existing table is dropped and a new table with this name is created.
        properties:
          type: object
          description: |
            Properties stored on the table, if supported by the implementation.
          additionalProperties:
            type: string

    CreateTableResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        location:
          type: string
        version:
          type: integer
          format: int64
          minimum: 0
        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

    CreateEmptyTableRequest:
      type: object
      deprecated: true
      description: |
        Request for creating an empty table.

        **Deprecated**: Use `DeclareTableRequest` instead.
      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: |
            Properties stored on the table, if supported by the server.
          additionalProperties:
            type: string

    CreateEmptyTableResponse:
      type: object
      deprecated: true
      description: |
        Response for creating an empty table.

        **Deprecated**: Use `DeclareTableResponse` instead.
      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

    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: |
            Properties stored on the table, if supported by the server.
          additionalProperties:
            type: string

    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.

    TableExistsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        version:
          description: |
            Version of the table to check existence.
            If not specified, server should resolve it to the latest version.
          type: integer
          format: int64
          minimum: 0

    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

    DescribeTransactionRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string

    DescribeTransactionResponse:
      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"

    AlterTransactionSetProperty:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        mode:
          $ref: "#/components/schemas/SetPropertyMode"

    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

    AlterTransactionUnsetProperty:
      type: object
      properties:
        key:
          type: string
        mode:
          $ref: "#/components/schemas/UnsetPropertyMode"

    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

    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"

    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"

    AlterTransactionResponse:
      type: object
      required:
        - status
      properties:
        status:
          $ref: "#/components/schemas/TransactionStatus"
        properties:
          type: object
          additionalProperties:
            type: string

    DropTableRequest:
      type: object
      description: |
        If the table and its data can be immediately deleted, return information of the deleted table.
        Otherwise, return a transaction ID that client can use to track deletion progress.
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string

    DropTableResponse:
      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

    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

    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

    StringFtsQuery:
      type: object
      required:
        - query
      properties:
        columns:
          type: array
          items:
            type: string
        query:
          type: string

    StructuredFtsQuery:
      type: object
      required:
        - query
      properties:
        query:
          $ref: "#/components/schemas/FtsQuery"

    FtsQuery:
      type: object
      description: |
        Full-text search query. Exactly one query type field must be provided.
        This structure follows the same pattern as AlterTransactionAction to minimize
        differences and compatibility issues across codegen in different languages.
      properties:
        match:
          $ref: "#/components/schemas/MatchQuery"
        phrase:
          $ref: "#/components/schemas/PhraseQuery"
        boost:
          $ref: "#/components/schemas/BoostQuery"
        multi_match:
          $ref: "#/components/schemas/MultiMatchQuery"
        boolean:
          $ref: "#/components/schemas/BooleanQuery"

    MatchQuery:
      type: object
      required:
        - terms
      properties:
        boost:
          type: number
          format: float
        column:
          type: string
        fuzziness:
          type: integer
          format: int32
          minimum: 0
        max_expansions:
          type: integer
          description: |-
            The maximum number of terms to expand for fuzzy matching.
            Default to 50.
          minimum: 0
        operator:
          $ref: "#/components/schemas/Operator"
          description: |-
            The operator to use for combining terms.
            This can be either `And` or `Or`, it's 'Or' by default.
            - `And`: All terms must match.
            - `Or`: At least one term must match.
        prefix_length:
          type: integer
          format: int32
          description: |-
            The number of beginning characters being unchanged for fuzzy matching.
            Default to 0.
          minimum: 0
        terms:
          type: string

    PhraseQuery:
      type: object
      required:
        - terms
      properties:
        column:
          type: string
        slop:
          type: integer
          format: int32
          minimum: 0
        terms:
          type: string

    BoostQuery:
      type: object
      description: Boost query that scores documents matching positive query higher and negative query lower
      required:
        - positive
        - negative
      properties:
        positive:
          $ref: "#/components/schemas/FtsQuery"
        negative:
          $ref: "#/components/schemas/FtsQuery"
        negative_boost:
          type: number
          format: float
          description: "Boost factor for negative query (default: 0.5)"
          default: 0.5

    MultiMatchQuery:
      type: object
      required:
        - match_queries
      properties:
        match_queries:
          type: array
          items:
            $ref: "#/components/schemas/MatchQuery"

    BooleanQuery:
      type: object
      description: Boolean query with must, should, and must_not clauses
      required:
        - should
        - must
        - must_not
      properties:
        must:
          type: array
          items:
            $ref: "#/components/schemas/FtsQuery"
          description: Queries that must match (AND)
        must_not:
          type: array
          items:
            $ref: "#/components/schemas/FtsQuery"
          description: Queries that must not match (NOT)
        should:
          type: array
          items:
            $ref: "#/components/schemas/FtsQuery"
          description: Queries that should match (OR)

    Operator:
      type: string
      description: |
        The operator to use for combining terms.
        Case insensitive, supports both PascalCase and snake_case. Valid values are:
        - And: All terms must match.
        - Or: At least one term must match.

    GetTableTagVersionRequest:
      type: object
      required:
        - tag
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to get version for

    GetTableTagVersionResponse:
      type: object
      required:
        - version
      properties:
        version:
          type: integer
          format: int64
          minimum: 0
          description: version number that the tag points to

    CreateTableTagRequest:
      type: object
      required:
        - tag
        - version
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to create
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version number for the tag to point to

    CreateTableTagResponse:
      type: object
      description: Response for create tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    DeleteTableTagRequest:
      type: object
      required:
        - tag
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to delete

    DeleteTableTagResponse:
      type: object
      description: Response for delete tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    UpdateTableTagRequest:
      type: object
      required:
        - tag
        - version
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to update
        version:
          type: integer
          format: int64
          minimum: 0
          description: New version number for the tag to point to

    UpdateTableTagResponse:
      type: object
      description: Response for update tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    ListTableTagsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
          description: The table identifier
        page_token:
          $ref: "#/components/schemas/PageToken"
        limit:
          $ref: "#/components/schemas/PageLimit"

    ListTableTagsResponse:
      type: object
      description: Response containing table tags
      required:
        - tags
      properties:
        tags:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TagContents"
          description: Map of tag names to their contents
        page_token:
          $ref: "#/components/schemas/PageToken"

    TagContents:
      type: object
      required:
        - version
        - manifestSize
      properties:
        branch:
          type: string
          description: Branch name that the tag was created on (if any)
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version number that the tag points to
        manifestSize:
          type: integer
          format: int64
          minimum: 0
          description: Size of the manifest file in bytes

    RestoreTableRequest:
      type: object
      required:
        - version
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version to restore to

    RestoreTableResponse:
      type: object
      description: Response for restore table operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    RenameTableRequest:
      type: object
      required:
        - new_table_name
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
          description: The table identifier
        new_table_name:
          type: string
          description: New name for the table
        new_namespace_id:
          type: array
          items:
            type: string
          description: New namespace identifier to move the table to (optional, if not specified the table stays in the same namespace)

    RenameTableResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    UpdateTableSchemaMetadataRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
          description: The table identifier
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Schema metadata key-value pairs to set

    UpdateTableSchemaMetadataResponse:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties:
            type: string
          description: The updated schema metadata
        transaction_id:
          type: string
          description: Optional transaction identifier

    ListTableVersionsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        page_token:
          $ref: "#/components/schemas/PageToken"
        limit:
          $ref: "#/components/schemas/PageLimit"
        descending:
          type: boolean
          description: |
            When true, versions are guaranteed to be returned in descending order (latest to oldest).
            When false or not specified, the ordering is implementation-defined.

    ListTableVersionsResponse:
      type: object
      required:
        - versions
      properties:
        versions:
          type: array
          items:
            $ref: "#/components/schemas/TableVersion"
          description: |
            List of table versions. When `descending=true`, guaranteed to be ordered from latest to oldest.
            Otherwise, ordering is implementation-defined.
        page_token:
          $ref: "#/components/schemas/PageToken"

    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"

    CreateTableVersionResponse:
      type: object
      description: Response for creating a table version
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        version:
          $ref: "#/components/schemas/TableVersion"

    DescribeTableVersionRequest:
      type: object
      description: Request to describe a specific table version
      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 describe

    DescribeTableVersionResponse:
      type: object
      description: Response containing the table version information
      required:
        - version
      properties:
        version:
          $ref: "#/components/schemas/TableVersion"
          description: The table version information

    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.

    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.

    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

    BatchCreateTableVersionsRequest:
      type: object
      description: |
        Request to atomically create new version entries for multiple tables.
        The operation is atomic: all versions are created or none are.
      required:
        - entries
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        entries:
          type: array
          items:
            $ref: "#/components/schemas/CreateTableVersionEntry"
          description: List of table version entries to create atomically

    CreateTableVersionEntry:
      type: object
      description: |
        An entry for creating a new table version in a batch operation.
        This supports `put_if_not_exists` semantics,
        where the operation fails if the version already exists.
      required:
        - id
        - version
        - manifest_path
      properties:
        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"

    BatchCreateTableVersionsResponse:
      type: object
      description: |
        Response for batch creating table versions.
        Contains the created versions for each table in the same order as the request.
      required:
        - versions
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        versions:
          type: array
          items:
            $ref: "#/components/schemas/TableVersion"
          description: List of created table versions in the same order as the request entries

    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.

    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

    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

    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.

    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

    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

    ExplainTableQueryPlanRequest:
      type: object
      required:
        - query
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        query:
          $ref: "#/components/schemas/QueryTableRequest"
        verbose:
          type: boolean
          default: false
          description: Whether to return verbose explanation

    ExplainTableQueryPlanResponse:
      type: object
      required:
        - plan
      properties:
        plan:
          type: string
          description: Human-readable query execution plan

    AnalyzeTableQueryPlanRequest:
      type: object
      required:
        - vector
        - k
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        bypass_vector_index:
          type: boolean
          description: Whether to bypass vector index
        columns:
          type: object
          nullable: true
          description: |
            Optional columns to return. Provide either column_names or column_aliases, not both.
          properties:
            column_names:
              type: array
              items:
                type: string
              description: List of column names to return
            column_aliases:
              type: object
              additionalProperties:
                type: string
              description: Object mapping output aliases to source column names
        distance_type:
          type: string
          description: Distance metric to use
        ef:
          type: integer
          minimum: 0
          description: Search effort parameter for HNSW index
        fast_search:
          type: boolean
          description: Whether to use fast search
        filter:
          type: string
          description: Optional SQL filter expression
        full_text_query:
          type: object
          nullable: true
          description: Optional full-text search query. Provide either string_query or structured_query, not both.
          properties:
            string_query:
              $ref: "#/components/schemas/StringFtsQuery"
            structured_query:
              $ref: "#/components/schemas/StructuredFtsQuery"
        k:
          type: integer
          minimum: 0
          description: Number of results to return
        lower_bound:
          type: number
          format: float
          description: Lower bound for search
        nprobes:
          type: integer
          minimum: 0
          description: Number of probes for IVF index
        offset:
          type: integer
          minimum: 0
          description: Number of results to skip
        prefilter:
          type: boolean
          description: Whether to apply filtering before vector search
        refine_factor:
          type: integer
          format: int32
          minimum: 0
          description: Refine factor for search
        upper_bound:
          type: number
          format: float
          description: Upper bound for search
        vector:
          type: object
          nullable: true
          description: Query vector(s) for similarity search. Provide either single_vector or multi_vector, not both.
          properties:
            single_vector:
              type: array
              items:
                type: number
                format: float
              description: Single query vector
            multi_vector:
              type: array
              items:
                type: array
                items:
                  type: number
                  format: float
              description: Multiple query vectors for batch search
        vector_column:
          type: string
          description: Name of the vector column to search
        version:
          type: integer
          format: int64
          minimum: 0
          description: Table version to query
        with_row_id:
          type: boolean
          description: If true, return the row id as a column called `_rowid`

    AnalyzeTableQueryPlanResponse:
      type: object
      required:
        - analysis
      properties:
        analysis:
          type: string
          description: Detailed analysis of the query execution plan

    AlterTableAddColumnsRequest:
      type: object
      required:
        - new_columns
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        new_columns:
          type: array
          items:
            $ref: "#/components/schemas/NewColumnTransform"
          description: List of new columns to add

    NewColumnTransform:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the new column
        expression:
          type: string
          nullable: true
          description: SQL expression to compute the column value (optional if virtual_column is specified)
        virtual_column:
          $ref: "#/components/schemas/AddVirtualColumnEntry"
          nullable: true
          description: Virtual column definition (optional if expression is specified)

    AddVirtualColumnEntry:
      type: object
      required:
        - input_columns
        - data_type
        - image
        - udf_version
        - udf_name
        - udf
      properties:
        input_columns:
          type: array
          items:
            type: string
          description: List of input column names for the virtual column
        data_type:
          type: object
          description: Data type of the virtual column using JSON representation
        image:
          type: string
          description: Docker image to use for the UDF
        udf:
          type: string
          description: Base64 encoded pickled UDF
        udf_name:
          type: string
          description: Name of the UDF
        udf_version:
          type: string
          description: Version of the UDF

    AlterTableAddColumnsResponse:
      type: object
      required:
        - version
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version of the table after adding columns

    AlterTableAlterColumnsRequest:
      type: object
      required:
        - alterations
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        alterations:
          type: array
          items:
            $ref: "#/components/schemas/AlterColumnsEntry"
          description: List of column alterations to perform

    AlterColumnsEntry:
      type: object
      required:
        - path
        - data_type
      properties:
        path:
          type: string
          description: Column path to alter
        data_type:
          type: object
          description: New data type for the column using JSON representation (optional)
        rename:
          type: string
          nullable: true
          description: New name for the column (optional)
        nullable:
          type: boolean
          nullable: true
          description: Whether the column should be nullable (optional)
        virtual_column:
          $ref: "#/components/schemas/AlterVirtualColumnEntry"
          nullable: true
          description: Virtual column alterations (optional)

    AlterVirtualColumnEntry:
      type: object
      properties:
        input_columns:
          type: array
          items:
            type: string
          nullable: true
          description: List of input column names for the virtual column (optional)
        image:
          type: string
          nullable: true
          description: Docker image to use for the UDF (optional)
        udf:
          type: string
          nullable: true
          description: Base64 encoded pickled UDF (optional)
        udf_name:
          type: string
          nullable: true
          description: Name of the UDF (optional)
        udf_version:
          type: string
          nullable: true
          description: Version of the UDF (optional)

    AlterTableAlterColumnsResponse:
      type: object
      required:
        - version
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version of the table after altering columns

    AlterTableDropColumnsRequest:
      type: object
      required:
        - columns
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        columns:
          type: array
          items:
            type: string
          description: Names of columns to drop

    AlterTableDropColumnsResponse:
      type: object
      required:
        - version
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version of the table after dropping columns

    GetTableStatsRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string

    GetTableStatsResponse:
      type: object
      required:
        - total_bytes
        - num_rows
        - num_indices
        - fragment_stats
      properties:
        total_bytes:
          type: integer
          format: int64
          minimum: 0
          description: The total number of bytes in the table
        num_rows:
          type: integer
          format: int64
          minimum: 0
          description: The number of rows in the table
        num_indices:
          type: integer
          format: int64
          minimum: 0
          description: The number of indices in the table
        fragment_stats:
          $ref: "#/components/schemas/FragmentStats"
          description: Statistics on table fragments

    FragmentStats:
      type: object
      required:
        - num_fragments
        - num_small_fragments
        - lengths
      properties:
        num_fragments:
          type: integer
          format: int64
          minimum: 0
          description: The number of fragments in the table
        num_small_fragments:
          type: integer
          format: int64
          minimum: 0
          description: The number of uncompacted fragments in the table
        lengths:
          $ref: "#/components/schemas/FragmentSummary"
          description: Statistics on the number of rows in the table fragments

    FragmentSummary:
      type: object
      required:
        - min
        - max
        - mean
        - p25
        - p50
        - p75
        - p99
      properties:
        min:
          type: integer
          format: int64
          minimum: 0
        max:
          type: integer
          format: int64
          minimum: 0
        mean:
          type: integer
          format: int64
          minimum: 0
        p25:
          type: integer
          format: int64
          minimum: 0
        p50:
          type: integer
          format: int64
          minimum: 0
        p75:
          type: integer
          format: int64
          minimum: 0
        p99:
          type: integer
          format: int64
          minimum: 0

    DropTableIndexRequest:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/Identity"
        context:
          $ref: "#/components/schemas/Context"
        id:
          type: array
          items:
            type: string
        index_name:
          type: string
          description: Name of the index to drop

    DropTableIndexResponse:
      type: object
      description: Response for drop index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier

    PartitionTransform:
      type: object
      description: Well-known partition transform
      required:
        - type
      properties:
        type:
          type: string
          description: Transform type (identity, year, month, day, hour, bucket, multi_bucket, truncate)
        num_buckets:
          type: integer
          description: Number of buckets for bucket transforms
        width:
          type: integer
          description: Truncation width for truncate transforms

    PartitionField:
      type: object
      description: Partition field definition
      required:
        - field_id
        - source_ids
        - result_type
      properties:
        field_id:
          type: string
          description: Unique identifier for this partition field (must not be renamed)
          example: "event_year"
        source_ids:
          type: array
          items:
            type: integer
          description: Field IDs of the source columns in the schema
          example: [1]
        transform:
          $ref: "#/components/schemas/PartitionTransform"
          description: Well-known partition transform. Exactly one of transform or expression must be specified.
        expression:
          type: string
          description: DataFusion SQL expression using col0, col1, ... as column references. Exactly one of transform or expression must be specified.
          example: "date_part('year', col0)"
        result_type:
          $ref: "#/components/schemas/JsonArrowDataType"
          description: The output type of the partition value (JsonArrowDataType format)
          example: { "type": "int32" }

    PartitionSpec:
      type: object
      description: Partition spec definition
      required:
        - id
        - fields
      properties:
        id:
          type: integer
          description: The spec version ID
          example: 1
        fields:
          type: array
          items:
            $ref: "#/components/schemas/PartitionField"
          description: Array of partition field definitions

  responses:
    ListNamespacesResponse:
      description: A list of namespaces
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListNamespacesResponse"
          examples:
            NonEmptyResponse:
              $ref: "#/components/examples/ListNamespacesNonEmptyExample"
            EmptyResponse:
              $ref: "#/components/examples/ListNamespacesEmptyExample"

    DescribeNamespaceResponse:
      description:
        Returns a namespace, as well as any properties stored on the namespace if namespace properties
        are supported by the server.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DescribeNamespaceResponse"

    CreateNamespaceResponse:
      description: Result of creating a namespace
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateNamespaceResponse"

    DropNamespaceResponse:
      description: Result of dropping a namespace
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DropNamespaceResponse"

    ListTablesResponse:
      description: A list of tables
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListTablesResponse"

    DescribeTableResponse:
      description: Table properties result when loading a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DescribeTableResponse"

    CountTableRowsResponse:
      description: Result of counting rows in a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CountTableRowsResponse"

    CreateTableResponse:
      description: Table properties result when creating a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateTableResponse"

    InsertIntoTableResponse:
      description: Result of inserting records into a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InsertIntoTableResponse"

    MergeInsertIntoTableResponse:
      description: Result of merge insert operation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MergeInsertIntoTableResponse"

    RegisterTableResponse:
      description: Table properties result when registering a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RegisterTableResponse"

    DescribeTransactionResponse:
      description: Response of DescribeTransaction
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DescribeTransactionResponse"

    AlterTransactionResponse:
      description: Response of AlterTransaction
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AlterTransactionResponse"

    DropTableResponse:
      description: Response of DropTable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DropTableResponse"

    DeregisterTableResponse:
      description: Response of DeregisterTable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeregisterTableResponse"

    UpdateTableResponse:
      description: Update successful
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateTableResponse"

    DeleteFromTableResponse:
      description: Delete successful
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeleteFromTableResponse"

    QueryTableResponse:
      description: Query results in Arrow IPC file format
      content:
        application/vnd.apache.arrow.file:
          schema:
            type: string
            format: binary

    CreateTableIndexResponse:
      description: Index created successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateTableIndexResponse"

    CreateTableScalarIndexResponse:
      description: Scalar index created successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateTableScalarIndexResponse"

    ListTableIndicesResponse:
      description: List of indices on the table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListTableIndicesResponse"

    DescribeTableIndexStatsResponse:
      description: Index statistics
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DescribeTableIndexStatsResponse"

    # Tag operation responses

    ListTableTagsResponse:
      description: List of table tags
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListTableTagsResponse"

    GetTableTagVersionResponse:
      description: Tag version information
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GetTableTagVersionResponse"

    CreateTableTagResponse:
      description: Create tag response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateTableTagResponse"

    DeleteTableTagResponse:
      description: Delete tag response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeleteTableTagResponse"

    UpdateTableTagResponse:
      description: Update tag response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateTableTagResponse"

    # Table operation responses

    ListTableVersionsResponse:
      description: List of table versions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListTableVersionsResponse"

    CreateTableVersionResponse:
      description: Result of creating a table version
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateTableVersionResponse"

    DescribeTableVersionResponse:
      description: Table version information
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DescribeTableVersionResponse"

    BatchDeleteTableVersionsResponse:
      description: Result of deleting table version records
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BatchDeleteTableVersionsResponse"

    BatchCreateTableVersionsResponse:
      description: Result of atomically creating table versions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BatchCreateTableVersionsResponse"

    BatchCommitTablesResponse:
      description: Result of atomically committing a batch of mixed table operations
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BatchCommitTablesResponse"

    ExplainTableQueryPlanResponse:
      description: Query execution plan explanation
      content:
        application/json:
          schema:
            type: string
            description: Human-readable query execution plan

    AnalyzeTableQueryPlanResponse:
      description: Query execution plan analysis
      content:
        application/json:
          schema:
            type: string
            description: Human-readable query execution plan analysis

    AlterTableAddColumnsResponse:
      description: Add columns operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AlterTableAddColumnsResponse"

    AlterTableAlterColumnsResponse:
      description: Alter columns operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AlterTableAlterColumnsResponse"

    AlterTableDropColumnsResponse:
      description: Drop columns operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AlterTableDropColumnsResponse"

    GetTableStatsResponse:
      description: Table statistics
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GetTableStatsResponse"

    RestoreTableResponse:
      description: Table restore operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RestoreTableResponse"

    RenameTableResponse:
      description: Table rename operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RenameTableResponse"

    DropTableIndexResponse:
      description: Index drop operation result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DropTableIndexResponse"

    DeclareTableResponse:
      description: Table properties result when declaring a table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeclareTableResponse"

    CreateEmptyTableResponse:
      description: Table properties result when creating an empty table
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateEmptyTableResponse"

    # Error Responses

    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}",
            }

    UnsupportedOperationErrorResponse:
      description: Not Acceptable / Unsupported Operation. The server does not support this operation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            {
              "type": "/errors/unsupported-operation",
              "title": "The server does not support this operation",
              "status": 406,
              "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",
            }

    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",
            }

  examples:
    ListNamespacesEmptyExample:
      summary: An empty list of namespaces
      value: { "namespaces": [] }

    ListNamespacesNonEmptyExample:
      summary: A non-empty list of namespaces
      value: { "namespaces": ["accounting", "credits"] }

  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key