LanceDB Transaction API

openapi: 3.2.0
info:
  title: Lance Namespace Specification Transaction API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  description: 'This OpenAPI specification is a part of the Lance namespace specification. It contains 2 parts:


    The `components/schemas`, `components/responses`, `components/examples`, `tags` sections define

    the request and response shape for each operation in a Lance Namespace across all implementations.

    See https://lance.org/format/namespace/operations for more details.


    The `servers`, `security`, `paths`, `components/parameters` sections are for the

    Lance REST Namespace implementation, which defines a complete REST server that can work with Lance datasets.

    See https://lance.org/format/namespace/rest for more details.

    '
servers:
- url: '{scheme}://{host}:{port}/{basePath}'
  description: Generic server URL with all parts configurable
  variables:
    scheme:
      default: http
    host:
      default: localhost
    port:
      default: '2333'
    basePath:
      default: ''
- url: '{scheme}://{host}/{basePath}'
  description: Server URL when the port can be inferred from the scheme
  variables:
    scheme:
      default: http
    host:
      default: localhost
    basePath:
      default: ''
security:
- OAuth2: []
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Transaction
  description: 'Operations that are related to a transaction

    '
paths:
  /v1/transaction/{id}/describe:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Transaction
      summary: Describe information about a transaction
      operationId: DescribeTransaction
      description: 'Return a detailed information for a given transaction

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DescribeTransactionRequest'
      responses:
        200:
          $ref: '#/components/responses/DescribeTransactionResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/transaction/{id}/alter:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Transaction
      summary: Alter information of a transaction.
      operationId: AlterTransaction
      description: 'Alter a transaction with a list of actions such as setting status or properties.

        The server should either succeed and apply all actions, or fail and apply no action.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlterTransactionRequest'
      responses:
        200:
          $ref: '#/components/responses/AlterTransactionResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        409:
          $ref: '#/components/responses/ConflictErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
components:
  responses:
    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
    UnauthorizedErrorResponse:
      description: Unauthorized. The request lacks valid authentication credentials for the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/unauthorized-request
            title: No valid authentication credentials for the operation
            status: 401
            detail: ''
            instance: /v1/namespaces
    NotFoundErrorResponse:
      description: A server-side problem that means can not find the specified resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/not-found-error
            title: Not found Error
            status: 404
            detail: ''
            instance: /v1/namespaces/{ns}
    AlterTransactionResponse:
      description: Response of AlterTransaction
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlterTransactionResponse'
    DescribeTransactionResponse:
      description: Response of DescribeTransaction
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DescribeTransactionResponse'
    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
    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}
    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
    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
  schemas:
    AlterTransactionResponse:
      type: object
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/TransactionStatus'
        properties:
          type: object
          additionalProperties:
            type: string
    DescribeTransactionRequest:
      type: object
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
    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'
    TransactionStatus:
      type: string
      description: 'The status of a transaction.

        Case insensitive, supports both PascalCase and snake_case. Valid values are:

        - Queued: the transaction is queued and not yet started

        - Running: the transaction is currently running

        - Succeeded: the transaction has completed successfully

        - Failed: the transaction has failed

        - Canceled: the transaction was canceled

        '
    Context:
      type: object
      description: 'Arbitrary context for a request as key-value pairs.

        How to use the context is custom to the specific implementation.


        REST NAMESPACE ONLY

        Context entries are passed via HTTP headers using the naming convention

        `x-lance-ctx-<key>: <value>`. For example, a context entry

        `{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`.

        '
      additionalProperties:
        type: string
    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'
    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

        '
    AlterTransactionSetProperty:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        mode:
          $ref: '#/components/schemas/SetPropertyMode'
    AlterTransactionSetStatus:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TransactionStatus'
    ErrorResponse:
      type: object
      description: Common JSON error response model
      required:
      - code
      properties:
        error:
          type: string
          description: A brief, human-readable message about the error.
          example: Table 'users' not found in namespace 'production'
        code:
          type: integer
          minimum: 0
          description: "Lance Namespace error code identifying the error type.\n\nError codes:\n  0 - Unsupported: Operation not supported by this backend\n  1 - NamespaceNotFound: The specified namespace does not exist\n  2 - NamespaceAlreadyExists: A namespace with this name already exists\n  3 - NamespaceNotEmpty: Namespace contains tables or child namespaces\n  4 - TableNotFound: The specified table does not exist\n  5 - TableAlreadyExists: A table with this name already exists\n  6 - TableIndexNotFound: The specified table index does not exist\n  7 - TableIndexAlreadyExists: A table index with this name already exists\n  8 - TableTagNotFound: The specified table tag does not exist\n  9 - TableTagAlreadyExists: A table tag with this name already exists\n  10 - TransactionNotFound: The specified transaction does not exist\n  11 - TableVersionNotFound: The specified table version does not exist\n  12 - TableColumnNotFound: The specified table column does not exist\n  13 - InvalidInput: Malformed request or invalid parameters\n  14 - ConcurrentModification: Optimistic concurrency conflict\n  15 - PermissionDenied: User lacks permission for this operation\n  16 - Unauthenticated: Authentication credentials are missing or invalid\n  17 - ServiceUnavailable: Service is temporarily unavailable\n  18 - Internal: Unexpected server/implementation error\n  19 - InvalidTableState: Table is in an invalid state for the operation\n  20 - TableSchemaValidationError: Table schema validation failed\n"
          example: 4
        detail:
          type: string
          description: 'An optional human-readable explanation of the error.

            This can be used to record additional information such as stack trace.

            '
          example: The table may have been dropped or renamed
        instance:
          type: string
          description: 'A string that identifies the specific occurrence of the error.

            This can be a URI, a request or response ID,

            or anything that the implementation can recognize to trace specific occurrence of the error.

            '
          example: /v1/table/production$users/describe
    DescribeTransactionResponse:
      type: object
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/TransactionStatus'
        properties:
          type: object
          additionalProperties:
            type: string
    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>`).

            '
    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

        '
    AlterTransactionUnsetProperty:
      type: object
      properties:
        key:
          type: string
        mode:
          $ref: '#/components/schemas/UnsetPropertyMode'
  parameters:
    delimiter:
      name: delimiter
      description: 'An optional delimiter of the `string identifier`, following the Lance Namespace spec.

        When not specified, the `$` delimiter must be used.

        '
      in: query
      required: false
      schema:
        type: string
    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
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key