外观
本页尚未翻译
本页内容仍为英文原文，源自官方文档 api-reference/rest/table/declare-a-table。中文翻译正在分批进行中。
Declare a table
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.
OpenAPI
yaml
openapi: 3.1.1
info:
title: Lance Namespace Specification
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
description: >
This OpenAPI specification is a part of the Lance namespace specification.
It contains 2 parts:
The `components/schemas`, `components/responses`, `components/examples`,
`tags` sections define
the request and response shape for each operation in a Lance Namespace
across all implementations.
See https://lance.org/format/namespace/operations for more details.
The `servers`, `security`, `paths`, `components/parameters` sections are for
the
Lance REST Namespace implementation, which defines a complete REST server
that can work with Lance datasets.
See https://lance.org/format/namespace/rest for more details.
servers:
- url: http://localhost:2333
description: Default local server
- 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: Namespace
description: |
Operations that are related to a namespace
- name: Table
description: |
Operations that are related to a table
- name: Index
description: |
Operations that are related to an index
- name: Tag
description: |
Operations that are related to tags
- name: Transaction
description: |
Operations that are related to a transaction
- name: Metadata
description: >
Operations that only interact with object metadata and should be
computationally lightweight
- name: Data
description: >
Operations that interact with object data and might be computationally
intensive
paths:
/v1/table/{id}/declare:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/delimiter'
post:
tags:
- Table
- Metadata
summary: Declare a table
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.
operationId: DeclareTable
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'
components:
parameters:
id:
name: id
description: >
`string identifier` of an object in a namespace, following the Lance
Namespace spec.
When the value is equal to the delimiter, it represents the root
namespace.
For example, `v1/namespace/$/list` performs a `ListNamespace` on the
root namespace.
in: path
required: true
schema:
type: string
delimiter:
name: delimiter
description: >
An optional delimiter of the `string identifier`, following the Lance
Namespace spec.
When not specified, the `$` delimiter must be used.
in: query
required: false
schema:
type: string
schemas:
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
Identity:
type: object
description: |
Identity information of a request.
properties:
api_key:
type: string
description: |
API key for authentication.
REST NAMESPACE ONLY
This is passed via the `x-api-key` header.
auth_token:
type: string
description: |
Bearer token for authentication.
REST NAMESPACE ONLY
This is passed via the `Authorization` header
with the Bearer scheme (e.g., `Bearer <token>`).
Context:
type: object
description: >
Arbitrary context as key-value pairs.
How to use the context is custom to the specific implementation.
On a request, it carries caller-provided context to the implementation.
On a response, it carries implementation-provided context back to the
caller.
REST NAMESPACE ONLY
Context entries are mapped to and from HTTP headers using the `header.`
prefix:
- On a request, any entry whose key starts with `header.` is sent as an
HTTP
request header with the prefix stripped. For example, the entry
`{"header.Authorization": "Bearer abc"}` is sent as the request header
`Authorization: Bearer abc`.
- On a response, every HTTP response header is returned as an entry
whose key is the
header name prefixed with `header.`. For example, the response header
`x-request-id: abc123` is returned as the entry `{"header.x-request-id": "abc123"}`.
additionalProperties:
type: string
DeclareTableResponse:
type: object
description: |
Response for declaring a table.
properties:
context:
$ref: '#/components/schemas/Context'
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.
ErrorResponse:
type: object
description: Common JSON error response model
required:
- code
properties:
context:
$ref: '#/components/schemas/Context'
error:
type: string
description: A brief, human-readable message about the error.
example: Table 'users' not found in namespace 'production'
code:
type: integer
minimum: 0
description: |
Lance Namespace error code identifying the error type.
Error codes:
0 - Unsupported: Operation not supported by this backend
1 - NamespaceNotFound: The specified namespace does not exist
2 - NamespaceAlreadyExists: A namespace with this name already exists
3 - NamespaceNotEmpty: Namespace contains tables or child namespaces
4 - TableNotFound: The specified table does not exist
5 - TableAlreadyExists: A table with this name already exists
6 - TableIndexNotFound: The specified table index does not exist
7 - TableIndexAlreadyExists: A table index with this name already exists
8 - TableTagNotFound: The specified table tag does not exist
9 - TableTagAlreadyExists: A table tag with this name already exists
10 - TransactionNotFound: The specified transaction does not exist
11 - TableVersionNotFound: The specified table version does not exist
12 - TableColumnNotFound: The specified table field does not exist
13 - InvalidInput: Malformed request or invalid parameters
14 - ConcurrentModification: Optimistic concurrency conflict
15 - PermissionDenied: User lacks permission for this operation
16 - Unauthenticated: Authentication credentials are missing or invalid
17 - ServiceUnavailable: Service is temporarily unavailable
18 - Internal: Unexpected server/implementation error
19 - InvalidTableState: Table is in an invalid state for the operation
20 - TableSchemaValidationError: Table schema validation failed
21 - Throttling: Request rate limit exceeded
22 - TableBranchNotFound: The specified table branch does not exist
23 - TableBranchAlreadyExists: A table branch with this name already exists
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
responses:
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
UnauthorizedErrorResponse:
description: >-
Unauthorized. The request lacks valid authentication credentials for the
operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/unauthorized-request
title: No valid authentication credentials for the operation
status: 401
detail: ''
instance: /v1/namespaces
ForbiddenErrorResponse:
description: Forbidden. Authenticated user does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/forbidden-request
title: Not authorized to make this request
status: 403
detail: ''
instance: /v1/namespaces
NotFoundErrorResponse:
description: A server-side problem that means can not find the specified resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/not-found-error
title: Not found Error
status: 404
detail: ''
instance: /v1/namespaces/{ns}
ConflictErrorResponse:
description: The request conflicts with the current state of the target resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/conflict
title: The namespace has been concurrently modified
status: 409
detail: ''
instance: /v1/namespaces/{ns}
ServiceUnavailableErrorResponse:
description: >-
The service is not ready to handle the request. The client should wait
and retry. The service may additionally send a Retry-After header to
indicate when to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/service-unavailable
title: Slow down
status: 503
detail: ''
instance: /v1/namespaces
ServerErrorResponse:
description: >-
A server-side problem that might not be addressable from the client
side. Used for server 5xx errors without more specific documentation in
individual routes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /errors/server-error
title: Internal Server Error
status: 500
detail: ''
instance: /v1/namespaces
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: /oauth/token
scopes: {}
BearerAuth:
type: http
scheme: bearer
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key