Namespace Operations¶

The Lance Namespace Specification defines a list of operations that can be performed against any Lance namespace:

Operation ID	Current Version	Namespace	Table	Index	Metadata	Data	Transaction
CreateNamespace	1	✓			✓
ListNamespaces	1	✓			✓
DescribeNamespace	1	✓			✓
DropNamespace	1	✓			✓
NamespaceExists	1	✓			✓
ListTables	1	✓	✓		✓
RegisterTable	1		✓		✓
DescribeTable	1		✓		✓
TableExists	1		✓		✓
DropTable	1		✓		✓
DeregisterTable	1		✓		✓
InsertIntoTable	1		✓			✓
MergeInsertIntoTable	1		✓			✓
UpdateTable	1		✓			✓
DeleteFromTable	1		✓			✓
QueryTable	1		✓			✓
CountTableRows	1		✓			✓
CreateTable	1		✓			✓
CreateTableIndex	1		✓	✓	✓
ListTableIndices	1		✓	✓	✓
DescribeTableIndexStats	1		✓	✓	✓
DescribeTransaction	1				✓		✓
AlterTransaction	1				✓		✓

Operation Versioning¶

When backwards incompatible change is introduced, a new operation version needs to be created, with a naming convention of <operationId>V<version>, for example ListNamespacesV2, DescribeTableV3, etc.

Operation Request and Response Schema¶

In general, each operation has a request and response. The request and response schema is defined using JSON schema in the components/schemas section of the OpenAPI specification.

Note

For exceptions to this rule, see the Notes section of the operations

Error Response Model¶

All error responses follow the JSON error response model based on RFC-7807:

    ErrorResponse:
      type: object
      description: Common JSON error response model
      properties:
        error:
          type: string
          description: a brief, human-readable message about the error
          example: Incorrect username or password
        code:
          type: integer
          minimum: 400
          maximum: 600
          description: |
            HTTP style response code, where 4XX represents client side errors 
            and 5XX represents server side errors.

            For implementations that uses HTTP (e.g. REST namespace),
            this field can be optional in favor of the HTTP response status code.
            In case both values exist and do not match, the HTTP response status code should be used.
          example: 404
        type:
          type: string
          description: |
            An optional type identifier string for the error.
            This allows the implementation to specify their internal error type,
            which could be more detailed than the HTTP standard status code.
          example: /errors/incorrect-user-pass
        detail:
          type: string
          description: |
            an optional human-readable explanation of the error.
            This can be used to record information such as stack trace.
          example: Authentication failed due to incorrect username or password
        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: /login/log/abc123

HTTP Status Codes and Responses¶

400 - Bad Request Error Response¶

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

401 - Unauthorized Error Response¶

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

403 - Forbidden Error Response¶

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

404 - Not Found Error Response¶

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

406 - Unsupported Operation Error Response¶

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

409 - Conflict Error Response¶

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

503 - Service Unavailable Error Response¶

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

5XX - Server Error Response¶

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