RenameTable

Usage notes

Note

This API supports only Iceberg tables, not Lance tables. To rename Lance tables, use the Lance REST Namespace API or the Lance ecosystem (Spark, Trino, and other compute engines).

Specify at least one of newName and newNamespaceName. You can change the table name, the namespace, or both.
Use the versionToken parameter for optimistic locking to prevent concurrent operation conflicts.
The new table name must be unique within the destination namespace.

Permissions

API	Action	Description
RenameTable	oss:RenameTable	Renames a table and checks the table policy.

Request syntax

PUT /tables/{tableBucketARN}/{namespace}/{name}/rename HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
{
   "newNamespaceName": "string",
   "newName": "string",
   "versionToken": "string"
}

Request parameters

Parameter	Type	Required	Example	Description
tableBucketARN	String	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	ARN of the table bucket in the format `acs:osstables:{region}:{uid}:bucket/{bucketName}`. Specified in the URI.
namespace	String	Yes	my_namespace	Namespace that contains the table. Specified in the URI.
name	String	Yes	my_table	Current name of the table. Specified in the URI.
newNamespaceName	String	No	new_namespace	Destination namespace for the table. Specify at least one of `newNamespaceName` or `newName`. Specified in the request body.
newName	String	No	new_table	New table name. Must be 1 to 255 characters and contain only lowercase letters, digits, and underscores (_). Specify at least one of `newName` or `newNamespaceName`. Specified in the request body.
versionToken	String	No	aaabbb	Version token for optimistic locking to prevent concurrent operation conflicts. Specified in the request body.

Examples

Request example

PUT /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace/my_table/rename HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****


{
   "newNamespaceName": "new_namespace",
   "newName": "new_table",
   "versionToken": "aaabbb"
}

Response example

HTTP/1.1 204 No Content
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3

SDKs

These SDKs support RenameTable:

ossutil CLI

The ossutil command for RenameTable is rename-table.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	Invalid or malformed request.
ForbiddenException	403	Insufficient permissions for this operation.
NotFoundException	404	Resource not found.
ConflictException	409	Conflicts with a previous write operation.