openapi: 3.1.1 info: title: Lance Namespace Specification Data Table 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: Table description: 'Operations that are related to a table ' paths: /v1/namespace/{id}/table/list: parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' - $ref: '#/components/parameters/page_token' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/include_declared' get: tags: - Table 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 - `include_declared`: 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' /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 - `include_declared`: pass through query parameter of the same name ' parameters: - $ref: '#/components/parameters/delimiter' - $ref: '#/components/parameters/page_token' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/include_declared' 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 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' - $ref: '#/components/parameters/check_declared' post: tags: - Table 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`, `load_detailed_metadata`, and `check_declared` 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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' /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 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 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 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 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 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 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 - name: properties in: query required: false schema: type: string description: 'Business logic properties managed by the namespace implementation outside Lance context. The map is translated to a single JSON-encoded query parameter such as `properties={"user":"alice","team":"eng"}`. ' - name: storage_options in: query required: false schema: type: string description: 'Storage options that configure overrides for writing table data and metadata during table creation. These are passed to Lance for the write path. The map is translated to a single JSON-encoded query parameter such as `storage_options={"aws_region":"us-east-1","timeout":"30s"}`. ' post: tags: - Table 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.\n\nThe schema of the Arrow IPC stream is used as the table schema.\nIf the stream is empty, the API creates a new empty table.\n\nREST NAMESPACE ONLY\nREST namespace uses Arrow IPC stream as the request body.\nIt passes in the `CreateTableRequest` information in the following way:\n- `id`: pass through path parameter of the same name\n- `mode`: pass through query parameter of the same name\n- `properties`: serialize as a single JSON-encoded query parameter such as\n `properties={\"user\":\"alice\",\"team\":\"eng\"}`; these are business logic properties\n managed by the namespace implementation outside Lance context\n- `storage_options`: serialize as a single JSON-encoded query parameter such as\n `storage_options={\"aws_region\":\"us-east-1\",\"timeout\":\"30s\"}`; these configure\n write-time overrides for data and metadata written during table creation\n" 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' 409: $ref: '#/components/responses/ConflictErrorResponse' 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 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 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 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' /v1/table/{id}/backfill_column: parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' post: tags: - Table summary: Trigger an async column backfill job operationId: AlterTableBackfillColumns description: 'Trigger an asynchronous backfill job for a computed column on table `id`. The column must be a virtual (UDF-backed) column. Returns a job ID for tracking. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlterTableBackfillColumnsRequest' responses: 202: $ref: '#/components/responses/AlterTableBackfillColumnsResponse' 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_index: parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' post: tags: - Table 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_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 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 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 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 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' /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 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 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 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}/tags/create: parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' post: tags: - Table 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 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 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' components: schemas: CountTableRowsResponse: type: integer format: int64 description: 'Response containing the count of rows. Serializes transparently as just the number for backward compatibility. ' minimum: 0 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 UpdateTableTagResponse: type: object description: Response for update tag operation properties: transaction_id: type: string description: Optional transaction identifier 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 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 ManifestNamingScheme: type: string description: "The naming scheme used for manifest files in the `_versions/` directory.\n\nKnown values:\n- `V1`: `_versions/{version}.manifest` - Simple version-based naming\n- `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number\n (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores\n\nV2 is preferred for new tables as it enables efficient latest-version discovery\nwithout needing to list all versions.\n" example: V2 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' 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 DescribeTableVersionResponse: type: object description: Response containing the table version information required: - version properties: version: $ref: '#/components/schemas/TableVersion' description: The table version information 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 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 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) AlterTableBackfillColumnsResponse: type: object required: - job_id properties: job_id: type: string description: The job ID for tracking the backfill job 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 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. ' 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 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 MultiMatchQuery: type: object required: - match_queries properties: match_queries: type: array items: $ref: '#/components/schemas/MatchQuery' AlterColumnsEntry: type: object required: - path 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 - 'null' description: New name for the column (optional) nullable: type: - boolean - 'null' description: Whether the column should be nullable (optional) virtual_column: oneOf: - type: 'null' - $ref: '#/components/schemas/AlterVirtualColumnEntry' description: Virtual column alterations (optional) DeleteTableTagResponse: type: object description: Response for delete tag operation properties: transaction_id: type: string description: Optional transaction identifier 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 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 DropTableIndexResponse: type: object description: Response for drop index operation properties: transaction_id: type: string description: Optional transaction identifier RestoreTableResponse: type: object description: Response for restore table operation properties: transaction_id: type: string description: Optional transaction identifier AlterTableAddColumnsRequest: type: object required: - new_columns properties: identity: $ref: '#/components/schemas/Identity' id: type: array items: type: string description: Table identifier path (namespace + table name) new_columns: type: array items: $ref: '#/components/schemas/AddColumnsEntry' description: List of new columns to add to the table 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 AddColumnsEntry: type: object required: - name properties: name: type: string description: Name of the new column expression: type: - string - 'null' description: SQL expression for the column (optional if virtual_column is specified) virtual_column: oneOf: - type: 'null' - $ref: '#/components/schemas/AddVirtualColumnEntry' description: Virtual column definition (optional if expression is specified) 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 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 udf_backend: type: - string - 'null' description: UDF backend type (e.g. DockerUDFSpecV1) auto_backfill: type: - boolean - 'null' description: Whether to automatically backfill the column after creation manifest: type: - string - 'null' description: JSON-serialized manifest for the UDF environment manifest_checksum: type: - string - 'null' description: SHA-256 checksum of the manifest content field_metadata: type: - object - 'null' additionalProperties: type: string description: User-supplied field metadata (string key-value pairs) 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` 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 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 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. ' 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. ' 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 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 CreateTableVersionResponse: type: object description: Response for creating a table version properties: transaction_id: type: string description: Optional transaction identifier version: $ref: '#/components/schemas/TableVersion' 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 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' CreateTableIndexResponse: type: object description: Response for create index operation properties: transaction_id: type: string description: Optional transaction identifier 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 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 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,\nto differentiate the behavior when a table of the same name already exists.\nCase insensitive, supports both PascalCase and snake_case. Valid values are:\n * Create (default): the operation fails with 409.\n * Overwrite: the existing table registration is replaced with the new registration.\n" properties: type: object description: 'Properties stored on the table, if supported by the implementation. ' additionalProperties: type: string 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' 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: 'Business logic properties stored and managed by the namespace implementation outside Lance context. If the implementation does not support table properties, it should return null for this field. ' 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: 'Business logic properties stored and managed by the namespace implementation outside Lance context, if supported by the implementation. ' additionalProperties: type: string AlterVirtualColumnEntry: type: object properties: input_columns: type: - array - 'null' items: type: string description: List of input column names for the virtual column (optional) image: type: - string - 'null' description: Docker image to use for the UDF (optional) udf: type: - string - 'null' description: Base64 encoded pickled UDF (optional) udf_name: type: - string - 'null' description: Name of the UDF (optional) udf_version: type: - string - 'null' description: Version of the UDF (optional) udf_backend: type: - string - 'null' description: UDF backend type (e.g. DockerUDFSpecV1) (optional) auto_backfill: type: - boolean - 'null' description: Whether to automatically backfill the column (optional) manifest: type: - string - 'null' description: JSON-serialized manifest for the UDF environment (optional) manifest_checksum: type: - string - 'null' description: SHA-256 checksum of the manifest content (optional) field_metadata: type: - object - 'null' additionalProperties: type: string description: User-supplied field metadata (optional) 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 check_declared: description: 'Whether to check if the table exists only as a namespace declaration without storage data. Default is false. When true, the response should populate `is_only_declared`. When false, the implementation should return null for `is_only_declared` unless another option such as `load_detailed_metadata` requires checking declared-only table state. ' type: boolean default: false 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 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 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 nullable: true 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. When false, the table has storage components (data and metadata files). When null, the implementation did not check whether the table is only declared. Clients should treat an omitted value as null. Implementations should populate this field when `check_declared` is true or another option such as `load_detailed_metadata` requires checking declared-only table state. Operations like describe_table with load_detailed_metadata=true may fail for declared-only tables. ' 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' 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 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_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 AlterTableAlterColumnsRequest: type: object required: - alterations properties: identity: $ref: '#/components/schemas/Identity' id: type: array items: type: string description: Table identifier path (namespace + table name) alterations: type: array items: $ref: '#/components/schemas/AlterColumnsEntry' description: List of column alterations to apply to the table AlterTableBackfillColumnsRequest: type: object required: - column properties: identity: $ref: '#/components/schemas/Identity' id: type: array items: type: string description: Table identifier path (namespace + table name) column: type: string description: Column name to backfill where: type: - string - 'null' description: Optional WHERE clause filter concurrency: type: - integer - 'null' description: Optional concurrency override intra_applier_concurrency: type: - integer - 'null' description: Optional intra-applier concurrency override min_checkpoint_size: type: - integer - 'null' description: Optional minimum checkpoint size max_checkpoint_size: type: - integer - 'null' description: Optional maximum checkpoint size batch_checkpoint_flush_interval_seconds: type: - number - 'null' description: Optional batch checkpoint flush interval in seconds read_version: type: - integer - 'null' description: Optional table version to read from task_size: type: - integer - 'null' description: Optional task size num_frags: type: - integer - 'null' description: Optional number of fragments checkpoint_size: type: - integer - 'null' description: Optional checkpoint size commit_granularity: type: - integer - 'null' description: Optional commit granularity cluster: type: - string - 'null' description: Optional cluster name manifest: type: - string - 'null' description: Optional manifest name 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 `). ' CreateTableTagResponse: type: object description: Response for create tag operation properties: transaction_id: type: string description: Optional transaction identifier 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 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 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 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 StringFtsQuery: type: object required: - query properties: columns: type: array items: type: string query: 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 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 CreateTableScalarIndexResponse: type: object description: Response for create scalar index operation properties: transaction_id: type: string description: Optional transaction identifier StructuredFtsQuery: type: object required: - query properties: query: $ref: '#/components/schemas/FtsQuery' 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) 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 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 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 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 RenameTableResponse: type: object properties: transaction_id: type: string description: Optional transaction identifier AlterTableAlterColumnsResponse: type: object required: - version properties: version: type: integer format: int64 description: The commit version associated with the operation minimum: 0 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 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 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' 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' 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 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 GetTableStatsRequest: type: object properties: identity: $ref: '#/components/schemas/Identity' context: $ref: '#/components/schemas/Context' id: type: array items: type: string 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. ' 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 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 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. ' 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` Context: type: object description: 'Arbitrary context for a request as key-value pairs. How to use the context is custom to the specific implementation. REST NAMESPACE ONLY Context entries are passed via HTTP headers using the naming convention `x-lance-ctx-: `. For example, a context entry `{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`. ' additionalProperties: type: string InsertIntoTableResponse: type: object description: Response from inserting records into a table properties: transaction_id: type: string description: Optional transaction identifier 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' 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 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' AlterTableAddColumnsResponse: type: object required: - version properties: version: type: integer format: int64 description: The commit version associated with the operation minimum: 0 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 PageLimit: description: 'An inclusive upper bound of the number of results that a caller will receive. ' type: integer nullable: true 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' GetTableTagVersionResponse: type: object required: - version properties: version: type: integer format: int64 minimum: 0 description: version number that the tag points to parameters: include_declared: name: include_declared description: 'When true (default), 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, only tables with storage components are returned. ' in: query required: false schema: type: boolean default: true page_token: name: page_token description: Pagination token from a previous request in: query required: false schema: $ref: '#/components/schemas/PageToken' 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 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 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 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 limit: name: limit description: Maximum number of items to return in: query required: false schema: $ref: '#/components/schemas/PageLimit' check_declared: name: check_declared description: 'Whether to check if the table exists only as a namespace declaration without storage data. When false (default), the response should return null for `is_only_declared` unless another option such as `load_detailed_metadata` requires the check. ' in: query required: false schema: type: boolean default: false responses: CreateTableResponse: description: Table properties result when creating a table content: application/json: schema: $ref: '#/components/schemas/CreateTableResponse' DropTableIndexResponse: description: Index drop operation result content: application/json: schema: $ref: '#/components/schemas/DropTableIndexResponse' CreateTableIndexResponse: description: Index created successfully content: application/json: schema: $ref: '#/components/schemas/CreateTableIndexResponse' DescribeTableResponse: description: Table properties result when loading a table content: application/json: schema: $ref: '#/components/schemas/DescribeTableResponse' MergeInsertIntoTableResponse: description: Result of merge insert operation content: application/json: schema: $ref: '#/components/schemas/MergeInsertIntoTableResponse' ListTablesResponse: description: A list of tables content: application/json: schema: $ref: '#/components/schemas/ListTablesResponse' 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 DeleteTableTagResponse: description: Delete tag response content: application/json: schema: $ref: '#/components/schemas/DeleteTableTagResponse' DropTableResponse: description: Response of DropTable content: application/json: schema: $ref: '#/components/schemas/DropTableResponse' AlterTableAddColumnsResponse: description: Add columns operation result content: application/json: schema: $ref: '#/components/schemas/AlterTableAddColumnsResponse' DescribeTableIndexStatsResponse: description: Index statistics content: application/json: schema: $ref: '#/components/schemas/DescribeTableIndexStatsResponse' 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 UpdateTableTagResponse: description: Update tag response content: application/json: schema: $ref: '#/components/schemas/UpdateTableTagResponse' InsertIntoTableResponse: description: Result of inserting records into a table content: application/json: schema: $ref: '#/components/schemas/InsertIntoTableResponse' ListTableTagsResponse: description: List of table tags content: application/json: schema: $ref: '#/components/schemas/ListTableTagsResponse' DescribeTableVersionResponse: description: Table version information content: application/json: schema: $ref: '#/components/schemas/DescribeTableVersionResponse' AlterTableAlterColumnsResponse: description: Alter columns operation result content: application/json: schema: $ref: '#/components/schemas/AlterTableAlterColumnsResponse' CreateTableTagResponse: description: Create tag response content: application/json: schema: $ref: '#/components/schemas/CreateTableTagResponse' 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 DeregisterTableResponse: description: Response of DeregisterTable content: application/json: schema: $ref: '#/components/schemas/DeregisterTableResponse' CreateTableVersionResponse: description: Result of creating a table version content: application/json: schema: $ref: '#/components/schemas/CreateTableVersionResponse' 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 DeclareTableResponse: description: Table properties result when declaring a table content: application/json: schema: $ref: '#/components/schemas/DeclareTableResponse' 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 DeleteFromTableResponse: description: Delete successful content: application/json: schema: $ref: '#/components/schemas/DeleteFromTableResponse' CountTableRowsResponse: description: Result of counting rows in a table content: application/json: schema: $ref: '#/components/schemas/CountTableRowsResponse' RegisterTableResponse: description: Table properties result when registering a table content: application/json: schema: $ref: '#/components/schemas/RegisterTableResponse' ListTableVersionsResponse: description: List of table versions content: application/json: schema: $ref: '#/components/schemas/ListTableVersionsResponse' BatchDeleteTableVersionsResponse: description: Result of deleting table version records content: application/json: schema: $ref: '#/components/schemas/BatchDeleteTableVersionsResponse' RestoreTableResponse: description: Table restore operation result content: application/json: schema: $ref: '#/components/schemas/RestoreTableResponse' AlterTableBackfillColumnsResponse: description: Backfill job accepted content: application/json: schema: $ref: '#/components/schemas/AlterTableBackfillColumnsResponse' 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 UpdateTableResponse: description: Update successful content: application/json: schema: $ref: '#/components/schemas/UpdateTableResponse' QueryTableResponse: description: Query results in Arrow IPC file format content: application/vnd.apache.arrow.file: schema: type: string format: binary ListTableIndicesResponse: description: List of indices on the table content: application/json: schema: $ref: '#/components/schemas/ListTableIndicesResponse' 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} BatchCreateTableVersionsResponse: description: Result of atomically creating table versions content: application/json: schema: $ref: '#/components/schemas/BatchCreateTableVersionsResponse' AnalyzeTableQueryPlanResponse: description: Query execution plan analysis content: application/json: schema: type: string description: Human-readable query execution plan analysis 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' 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 GetTableTagVersionResponse: description: Tag version information content: application/json: schema: $ref: '#/components/schemas/GetTableTagVersionResponse' RenameTableResponse: description: Table rename operation result content: application/json: schema: $ref: '#/components/schemas/RenameTableResponse' 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} CreateTableScalarIndexResponse: description: Scalar index created successfully content: application/json: schema: $ref: '#/components/schemas/CreateTableScalarIndexResponse' securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: /oauth/token scopes: {} BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: x-api-key