Lance REST Namespace API 兼容情况说明-对象存储(OSS)-阿里云帮助中心

OSS Tables 提供兼容 Lance REST Namespace 的 API 端点。本文按接口、参数、鉴权三个维度，说明 OSS Tables 与 Lance Namespace 标准协议在请求参数、响应字段和行为语义上的差异，帮助您在开发自研客户端或选择计算引擎时评估兼容范围。

兼容设计原则

OSS Tables 的 Lance REST Namespace 接口在设计上遵循以下原则：

优先遵循标准协议：尽可能按 Lance REST Namespace 规范实现接口、参数和响应语义；受 TableBucket 模型约束的能力明确列出差异与限制。
遵循 TableBucket 资源模型：由服务端统一管理命名空间、表及存储位置，仅支持单级命名空间，不支持通过 RegisterTable 注册任意已有存储位置。
统一使用 V4 签名鉴权：支持 AWS SigV4 和 OSS V4，签名服务名均为 osstables，沿用 OSS Tables 权限体系；不支持凭证下发，客户端需自行配置数据访问凭证。
使用 Lance 原生版本管理：数据集版本由 Lance 管理，不采用 Namespace 托管版本机制，managed_versioning 返回 false。

访问端点与资源标识

OSS Tables 提供 Lance REST Namespace 端点，Lance 客户端通过该端点管理命名空间、表及表元数据。每个端点对应一个表存储桶，客户端连接时需指定表存储桶名称、所属账号和地域。Endpoint 格式如下：

网络类型	Endpoint
外网	`https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance`
内网	`https://{tableBucketName}-{uid}.{region}-internal.oss-tables.aliyuncs.com/lance`

tableBucketName：表存储桶名称；uid：所属阿里云账号 UID；region：地域 ID。
必须使用表存储桶所在地域的三级域名（{tableBucketName}-{uid} 前缀），不支持仅使用地域域名；缺失三级域名前缀会返回 LanceThirdLevelDomainRequired 错误。
表存储桶 ARN 无需拼接到路径或资源标识中。

接口路径中的 {id} 用于标识命名空间或表，由 SDK 标识数组中的各部分通过 delimiter 连接而成。默认分隔符为 $，作为 URL 路径传入时需进行 URL 编码。下表示例均使用默认分隔符。

资源	SDK 中的标识数组	REST 路径中的标识示例
根命名空间	空数组（长度为 0）	`$`，编码后为 `%24`
命名空间	`["my_db"]`	`my_db`
表	`["my_db", "my_table"]`	`my_db$my_table`，编码后为 `my_db%24my_table`

下文接口路径均相对于上述 Endpoint，实际请求地址由 Endpoint 与接口路径拼接而成。例如，查询 my_db 命名空间下 my_table 表的请求地址为 https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance/v1/table/my_db%24my_table/describe。

通用兼容限制

以下约束适用于相关接口，后续接口表不再重复列出。

项目	兼容情况
命名空间层级	仅支持单级命名空间，不支持多级命名空间或根命名空间直属表。
命名空间属性	不支持自定义命名空间属性，相关响应中的 `properties` 返回 `null`。
`delimiter`	默认值为 `$`；不得包含 `/`、`:`、`-`。
分页参数	`page_token` 符合 Lance Namespace 规范；`limit` 限定为 1～1000，默认 1000。
`context`	不处理自定义业务上下文。
事务	不返回 `transaction_id`，不支持异步事务及其进度查询。
版本管理	使用 Lance 原生版本管理；`managed_versioning` 固定为 `false`，不支持 Namespace 托管版本管理。

接口兼容情况

以下表格列出 OSS Tables 当前支持的 14 个 Lance Namespace 标准 API，包括 5 个命名空间接口和 9 个表接口。未列出的标准 API 暂不支持。

表格中的"路径"和"方法"用于构造 REST 请求，"操作"对应 Lance Namespace 标准操作名称。"兼容情况"列说明各接口的参数限制、响应差异及行为约束；除上文通用限制外无其他差异的接口，标注为"符合 Lance Namespace 规范"。

命名空间接口

路径	方法	操作	兼容情况
`/lance/v1/namespace/{id}/create`	POST	`CreateNamespace`	不支持创建根命名空间；不支持 `mode=Overwrite`。
`/lance/v1/namespace/{id}/list`	GET	`ListNamespaces`	符合 Lance Namespace 规范。
`/lance/v1/namespace/{id}/describe`	POST	`DescribeNamespace`	符合 Lance Namespace 规范。
`/lance/v1/namespace/{id}/exists`	POST	`NamespaceExists`	符合 Lance Namespace 规范。
`/lance/v1/namespace/{id}/drop`	POST	`DropNamespace`	不支持删除根命名空间；不支持 `behavior=Cascade`（级联删除），仅允许删除空命名空间。

表接口

路径	方法	操作	兼容情况
`/lance/v1/namespace/{id}/table/list`	GET	`ListTables`	`tables` 仅返回表名，不返回带命名空间的完整标识；仅支持 `include_declared=true`；不支持通过根命名空间递归列举全部表，跨命名空间列举使用 `ListAllTables`。
`/lance/v1/table`	GET	`ListAllTables`	仅支持 `include_declared=true`。
`/lance/v1/table/{id}/create`	POST	`CreateTable`	不支持 `mode=Overwrite`；Arrow IPC 请求体默认上限为 10 MiB；查询参数 `storage_options` 被忽略；表仅通过 `DeclareTable` 登记尚未创建 Lance 数据集时，`CreateTable(mode=ExistOk)` 保留已有表，不创建数据集并返回 `version=0`。
`/lance/v1/table/{id}/declare`	POST	`DeclareTable`	不允许指定非空 `location`，由服务端分配存储位置。
`/lance/v1/table/{id}/describe`	POST	`DescribeTable`	`version`、`branch` 仅在 `load_detailed_metadata=true` 或 `check_declared=true` 时生效，否则不验证目标版本或分支是否存在；不支持通过 `tag` 指定标签版本。
`/lance/v1/table/{id}/exists`	POST	`TableExists`	符合 Lance Namespace 规范。
`/lance/v1/table/{id}/drop`	POST	`DropTable`	表数据由后台清理，接口成功不表示物理数据已清理完成。
`/lance/v1/table/{id}/rename`	POST	`RenameTable`	符合 Lance Namespace 规范。
`/lance/v1/table/{id}/deregister`	POST	`DeregisterTable`	符合 Lance Namespace 规范，详见下方DeregisterTable 实现说明。

DeregisterTable 实现说明

DeregisterTable 用于注销表，不会删除数据。具体处理方式如下：

将表移入系统保留命名空间 oss-deregistered-ns。
表名改为 oss-deregistered-table-{tableId}，其中 tableId 为原表 ID；原表名可重新使用。
ListNamespaces 不列出保留命名空间，ListAllTables 不列出已注销的表。
调用 ListTables 列举 oss-deregistered-ns，可查看已注销的表。
如需真正删除，使用保留命名空间及列举返回的表名调用 DropTable，删除表及其数据。

鉴权机制与权限

OSS Tables Lance REST Namespace 接口仅支持 AWS SigV4 和 OSS V4 签名鉴权，签名服务名或产品名均为 osstables，签名地域为表存储桶所在地域。不支持 OAuth2、Bearer Token 和 API Key 鉴权。

鉴权方式	兼容情况
AWS SigV4	支持（推荐）。签名服务名为 `osstables`，签名地域为表存储桶所在地域。
OSS V4	支持。使用 OSS V4 签名规则，签名产品名为 `osstables`。
OAuth2、Bearer Token、`x-api-key`	不支持，需使用 OSS Tables 请求签名。
凭证下发（Credential Vending）	`DescribeTable`、`DeclareTable` 不支持 `vend_credentials=true`；不下发存储凭证，响应不返回 `storage_options`，客户端需自行配置存储访问凭证。