Lance REST Namespace API compatibility-阿里云帮助中心

Compatibility design principles

The Lance REST Namespace API of OSS Tables follows these design principles:

Follow the standard protocol first: APIs, parameters, and response semantics are implemented in accordance with the Lance REST Namespace specification whenever possible. Capabilities that are constrained by the TableBucket model have their differences and limitations explicitly listed.
Follow the TableBucket resource model: Namespaces, tables, and storage locations are managed by the server. Only single-level namespaces are supported, and registering arbitrary existing storage locations by using RegisterTable is not supported.
Use V4 signature authentication uniformly: AWS SigV4 and OSS V4 are supported. The signature service name is osstables, and the OSS Tables permission system is used. Credential vending is not supported, and clients must configure their own data access credentials.
Use Lance native versioning: Dataset versions are managed by Lance instead of by a Namespace-managed versioning mechanism. managed_versioning returns false.

Access endpoints and resource identifiers

OSS Tables provides Lance REST Namespace endpoints. Lance clients use these endpoints to manage namespaces, tables, and table metadata. Each endpoint corresponds to a table bucket. When a client connects, it must specify the table bucket name, the Alibaba Cloud account to which the bucket belongs, and the region. The endpoint format is as follows:

Network type	Endpoint
Public network	`https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance`
Internal network	`https://{tableBucketName}-{uid}.{region}-internal.oss-tables.aliyuncs.com/lance`

tableBucketName: the table bucket name; uid: the Alibaba Cloud account UID; region: the region ID.
You must use the third-level domain name of the region where the table bucket resides (the {tableBucketName}-{uid} prefix). Using only the regional domain name is not supported. If the third-level domain name prefix is missing, the LanceThirdLevelDomainRequired error is returned.
The table bucket ARN does not need to be appended to the path or resource identifier.

The {id} in the API path identifies a namespace or table. It is formed by joining the parts of the identifier array in the SDK with the delimiter. The default delimiter is $, which must be URL-encoded when passed as part of a URL path. The following examples all use the default delimiter.

Resource	Identifier array in the SDK	Example identifier in the REST path
Root namespace	Empty array (length 0)	`$`, which is encoded as `%24`
Namespace	`["my_db"]`	`my_db`
Table	`["my_db", "my_table"]`	`my_db$my_table`, which is encoded as `my_db%24my_table`

The API paths in the following sections are all relative to the preceding endpoint. The actual request URL is formed by concatenating the endpoint and the API path. For example, the request URL for querying the my_table table in the my_db namespace is https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance/v1/table/my_db%24my_table/describe.

General compatibility constraints

The following constraints apply to the relevant APIs and are not repeated in the subsequent API tables.

Item	Compatibility
Namespace levels	Only single-level namespaces are supported. Multi-level namespaces and tables directly under the root namespace are not supported.
Namespace properties	Custom namespace properties are not supported. `properties` in the relevant responses returns `null`.
`delimiter`	The default value is `$`. The delimiter must not contain `/`, `:`, or `-`.
Pagination parameters	`page_token` complies with the Lance Namespace specification. `limit` ranges from 1 to 1000, and the default value is 1000.
`context`	Custom business contexts are not processed.
Transactions	`transaction_id` is not returned. Asynchronous transactions and their progress queries are not supported.
Version management	Lance native versioning is used. `managed_versioning` is fixed to `false`. Namespace-managed versioning is not supported.

API compatibility

The following tables list the 14 Lance Namespace standard APIs currently supported by OSS Tables, including 5 namespace APIs and 9 table APIs. Standard APIs that are not listed are not supported.

In the tables, "Path" and "Method" are used to construct REST requests, and "Operation" corresponds to the standard Lance Namespace operation name. The "Compatibility" column describes the parameter constraints, response differences, and behavioral constraints of each API. APIs that have no differences other than the general constraints described above are marked as "Compliant with the Lance Namespace specification."

Namespace APIs

Path	Method	Operation	Compatibility
`/lance/v1/namespace/{id}/create`	POST	`CreateNamespace`	Creating a root namespace is not supported. `mode=Overwrite` is not supported.
`/lance/v1/namespace/{id}/list`	GET	`ListNamespaces`	Compliant with the Lance Namespace specification.
`/lance/v1/namespace/{id}/describe`	POST	`DescribeNamespace`	Compliant with the Lance Namespace specification.
`/lance/v1/namespace/{id}/exists`	POST	`NamespaceExists`	Compliant with the Lance Namespace specification.
`/lance/v1/namespace/{id}/drop`	POST	`DropNamespace`	Dropping a root namespace is not supported. `behavior=Cascade` (cascade deletion) is not supported. Only empty namespaces can be dropped.

Table APIs

Path	Method	Operation	Compatibility
`/lance/v1/namespace/{id}/table/list`	GET	`ListTables`	`tables` returns only table names, not fully qualified identifiers that include the namespace. Only `include_declared=true` is supported. Recursively listing all tables through the root namespace is not supported. To list tables across namespaces, use `ListAllTables`.
`/lance/v1/table`	GET	`ListAllTables`	Only `include_declared=true` is supported.
`/lance/v1/table/{id}/create`	POST	`CreateTable`	`mode=Overwrite` is not supported. The default upper limit of the Arrow IPC request body is 10 MiB. The `storage_options` query parameter is ignored. If a table is only declared by using `DeclareTable` and no Lance dataset has been created, `CreateTable(mode=ExistOk)` retains the existing table, does not create a dataset, and returns `version=0`.
`/lance/v1/table/{id}/declare`	POST	`DeclareTable`	Specifying a non-empty `location` is not allowed. The storage location is allocated by the server.
`/lance/v1/table/{id}/describe`	POST	`DescribeTable`	`version` and `branch` take effect only when `load_detailed_metadata=true` or `check_declared=true` is specified. Otherwise, the existence of the target version or branch is not validated. Specifying a tag version by using `tag` is not supported.
`/lance/v1/table/{id}/exists`	POST	`TableExists`	Compliant with the Lance Namespace specification.
`/lance/v1/table/{id}/drop`	POST	`DropTable`	Table data is cleaned up in the background. A successful API call does not indicate that the physical data has been cleaned up.
`/lance/v1/table/{id}/rename`	POST	`RenameTable`	Compliant with the Lance Namespace specification.
`/lance/v1/table/{id}/deregister`	POST	`DeregisterTable`	Compliant with the Lance Namespace specification. For more information, see the following DeregisterTable implementation notes.

DeregisterTable implementation notes

DeregisterTable is used to deregister a table and does not delete data. The processing logic is as follows:

The table is moved to the system-reserved namespace oss-deregistered-ns.
The table is renamed to oss-deregistered-table-{tableId}, where tableId is the original table ID. The original table name can be reused.
ListNamespaces does not list reserved namespaces, and ListAllTables does not list deregistered tables.
Call ListTables to list oss-deregistered-ns to view deregistered tables.
To permanently delete a table, call DropTable by using the reserved namespace and the table name returned by the listing operation. This deletes the table and its data.

Authentication mechanisms and permissions

The OSS Tables Lance REST Namespace APIs support only AWS SigV4 and OSS V4 signature authentication. The signature service name or product name is osstables, and the signature region is the region where the table bucket resides. OAuth2, Bearer Token, and API Key authentication are not supported.

Authentication method	Compatibility
AWS SigV4	Supported (recommended). The signature service name is `osstables`, and the signature region is the region where the table bucket resides.
OSS V4	Supported. Uses OSS V4 signature rules. The signature product name is `osstables`.
OAuth2, Bearer Token, `x-api-key`	Not supported. You must use OSS Tables request signatures.
Credential vending	`DescribeTable` and `DeclareTable` do not support `vend_credentials=true`. Storage credentials are not vendored, and responses do not return `storage_options`. Clients must configure their own storage access credentials.