命名空间操作¶
Lance 命名空间规范定义了一系列可对任何 Lance 命名空间执行的操作
| 操作 ID | 当前版本 | 命名空间 | 表 | 索引 | 元数据 | 数据 | 事务 |
|---|---|---|---|---|---|---|---|
| 创建命名空间 | 1 | ✓ | ✓ | ||||
| 列出命名空间 | 1 | ✓ | ✓ | ||||
| 描述命名空间 | 1 | ✓ | ✓ | ||||
| 删除命名空间 | 1 | ✓ | ✓ | ||||
| 命名空间存在 | 1 | ✓ | ✓ | ||||
| 列出表 | 1 | ✓ | ✓ | ✓ | |||
| 注册表 | 1 | ✓ | ✓ | ||||
| 描述表 | 1 | ✓ | ✓ | ||||
| 表存在 | 1 | ✓ | ✓ | ||||
| 删除表 | 1 | ✓ | ✓ | ||||
| 注销表 | 1 | ✓ | ✓ | ||||
| 插入到表 | 1 | ✓ | ✓ | ||||
| 合并插入到表 | 1 | ✓ | ✓ | ||||
| 更新表 | 1 | ✓ | ✓ | ||||
| 从表删除 | 1 | ✓ | ✓ | ||||
| 查询表 | 1 | ✓ | ✓ | ||||
| 计算表行数 | 1 | ✓ | ✓ | ||||
| 创建表 | 1 | ✓ | ✓ | ||||
| 创建表索引 | 1 | ✓ | ✓ | ✓ | |||
| 列出表索引 | 1 | ✓ | ✓ | ✓ | |||
| 描述表索引统计信息 | 1 | ✓ | ✓ | ✓ | |||
| 恢复表 | 1 | ✓ | ✓ | ||||
| 列出表版本 | 1 | ✓ | ✓ | ||||
| 解释表查询计划 | 1 | ✓ | ✓ | ||||
| 分析表查询计划 | 1 | ✓ | ✓ | ||||
| 修改表添加列 | 1 | ✓ | ✓ | ||||
| 修改表修改列 | 1 | ✓ | ✓ | ||||
| 修改表删除列 | 1 | ✓ | ✓ | ||||
| 获取表统计信息 | 1 | ✓ | ✓ | ||||
| 列出表标签 | 1 | ✓ | ✓ | ||||
| 获取表标签版本 | 1 | ✓ | ✓ | ||||
| 创建表标签 | 1 | ✓ | ✓ | ||||
| 删除表标签 | 1 | ✓ | ✓ | ||||
| 更新表标签 | 1 | ✓ | ✓ | ||||
| 删除表索引 | 1 | ✓ | ✓ | ✓ | |||
| 描述事务 | 1 | ✓ | ✓ | ||||
| 修改事务 | 1 | ✓ | ✓ |
操作版本控制¶
当引入不兼容的更改时，需要创建一个新的操作版本，其命名约定为 <operationId>V<version>，例如 ListNamespacesV2、DescribeTableV3 等。
操作请求和响应模式¶
通常，每个操作都有一个请求和响应。请求和响应模式是使用 OpenAPI 规范的 components/schemas 部分中的 JSON 模式定义的。
注意
有关此规则的例外情况，请参阅操作的“注释”部分
错误响应模型¶
所有错误响应都遵循基于 RFC-7807 的 JSON 错误响应模型
ErrorResponse:
type: object
description: Common JSON error response model
properties:
error:
type: string
description: a brief, human-readable message about the error
example: Incorrect username or password
code:
type: integer
minimum: 400
maximum: 600
description: |
HTTP style response code, where 4XX represents client side errors
and 5XX represents server side errors.
For implementations that uses HTTP (e.g. REST namespace),
this field can be optional in favor of the HTTP response status code.
In case both values exist and do not match, the HTTP response status code should be used.
example: 404
type:
type: string
description: |
An optional type identifier string for the error.
This allows the implementation to specify their internal error type,
which could be more detailed than the HTTP standard status code.
example: /errors/incorrect-user-pass
detail:
type: string
description: |
an optional human-readable explanation of the error.
This can be used to record information such as stack trace.
example: Authentication failed due to incorrect username or password
instance:
type: string
description: |
a string that identifies the specific occurrence of the error.
This can be a URI, a request or response ID,
or anything that the implementation can recognize to trace specific occurrence of the error.
example: /login/log/abc123
HTTP 状态码和响应¶
400 - 错误请求错误响应¶
BadRequestErrorResponse:
description:
Indicates a bad request error. It could be caused by an unexpected request
body format or other forms of request validation failure, such as invalid json.
Usually serves application/json content, although in some cases simple text/plain content might
be returned by the server's middleware.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/bad-request",
"title": "Malformed request",
"status": 400,
"detail": "",
"instance": "/v1/namespaces"
}
401 - 未授权错误响应¶
UnauthorizedErrorResponse:
description: Unauthorized. The request lacks valid authentication credentials for the operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/unauthorized-request",
"title": "No valid authentication credentials for the operation",
"status": 401,
"detail": "",
"instance": "/v1/namespaces"
}
403 - 禁止访问错误响应¶
ForbiddenErrorResponse:
description: Forbidden. Authenticated user does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/forbidden-request",
"title": "Not authorized to make this request",
"status": 403,
"detail": "",
"instance": "/v1/namespaces"
}
404 - 未找到错误响应¶
NotFoundErrorResponse:
description:
A server-side problem that means can not find the specified resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/not-found-error",
"title": "Not found Error",
"status": 404,
"detail": "",
"instance": "/v1/namespaces/{ns}"
}
406 - 不支持的操作错误响应¶
UnsupportedOperationErrorResponse:
description: Not Acceptable / Unsupported Operation. The server does not support this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/unsupported-operation",
"title": "The server does not support this operation",
"status": 406,
"detail": "",
"instance": "/v1/namespaces"
}
409 - 冲突错误响应¶
ConflictErrorResponse:
description: The request conflicts with the current state of the target resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/conflict",
"title": "The namespace has been concurrently modified",
"status": 409,
"detail": "",
"instance": "/v1/namespaces/{ns}"
}
503 - 服务不可用错误响应¶
ServiceUnavailableErrorResponse:
description:
The service is not ready to handle the request. The client should wait and retry.
The service may additionally send a Retry-After header to indicate when to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example: {
"type": "/errors/service-unavailable",
"title": "Slow down",
"status": 503,
"detail": "",
"instance": "/v1/namespaces"
}
5XX - 服务器错误响应¶
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"
}