From 82c155ca3381acb4f5f5761e251422adab5d0308 Mon Sep 17 00:00:00 2001 From: prrao87 <35005448+prrao87@users.noreply.github.com> Date: Mon, 22 Dec 2025 06:06:50 +0000 Subject: [PATCH] chore(docs): sync OpenAPI spec --- docs/api-reference/rest/openapi.yml | 158 ++++++++++++++++++++++------ lance-namespace | 1 + 2 files changed, 127 insertions(+), 32 deletions(-) create mode 160000 lance-namespace diff --git a/docs/api-reference/rest/openapi.yml b/docs/api-reference/rest/openapi.yml index 100e548..9f91707 100644 --- a/docs/api-reference/rest/openapi.yml +++ b/docs/api-reference/rest/openapi.yml @@ -439,7 +439,7 @@ paths: 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 (empty table created with CreateEmptyTable) + - A `.lance-reserved` file exists in the table directory (declared table created with DeclareTable) requestBody: required: true content: @@ -1529,6 +1529,46 @@ paths: 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' @@ -1539,12 +1579,15 @@ paths: - 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: @@ -1797,43 +1840,55 @@ components: 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: Incorrect username or password + description: A brief, human-readable message about the error. + example: Table 'users' not found in namespace 'production' 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 + minimum: 0 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 + 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 information such as stack trace. - example: Authentication failed due to incorrect username or password + 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, + 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 + example: /v1/table/production$users/describe CreateNamespaceRequest: type: object @@ -2717,8 +2772,11 @@ components: CreateEmptyTableRequest: type: object + deprecated: true description: | Request for creating an empty table. + + **Deprecated**: Use `DeclareTableRequest` instead. properties: id: type: array @@ -2729,25 +2787,54 @@ components: description: | Optional storage location for the table. If not provided, the namespace implementation should determine the table location. - properties: - type: object - 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 - properties: + 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 + + DeclareTableRequest: + type: object + description: | + Request for declaring a table. + properties: + 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. + + 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: | @@ -4084,6 +4171,13 @@ components: 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: @@ -4244,4 +4338,4 @@ components: ApiKeyAuth: type: apiKey in: header - name: x-api-key \ No newline at end of file + name: x-api-key diff --git a/lance-namespace b/lance-namespace new file mode 160000 index 0000000..3288b96 --- /dev/null +++ b/lance-namespace @@ -0,0 +1 @@ +Subproject commit 3288b96878aebf0d015834ee86b8df6b9b8e3d94