UpdateTableMetadataLocation-Object Storage Service(OSS)-阿里云帮助中心

Usage notes

Points a table to a new metadata file, enabling schema evolution and data commits.
Requires the current versionToken for optimistic locking to ensure consistency during concurrent updates.
Obtain the versionToken by calling the GetTableMetadataLocation or GetTable operation.
The new metadataLocation must point to a valid Iceberg metadata JSON file.

Permissions

API	Action	Description
UpdateTableMetadataLocation	oss:UpdateTableMetadataLocation	Updates the metadata location of a table. This operation also checks the table policy.

Request syntax

PUT /tables/{tableBucketARN}/{namespace}/{name}/metadata-location HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

{
   "versionToken": "string",
   "metadataLocation": "string"
}

Request parameters

Parameter	Type	Required	Example	Description
tableBucketARN	String	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	The ARN of the table's bucket. Format: `acs:osstables:{region}:{uid}:bucket/{bucketName}`. This parameter is in the URI.
namespace	String	Yes	my_namespace	The name of the table's namespace. This parameter is in the URI.
name	String	Yes	my_table	The name of the table. This parameter is in the URI.
versionToken	String	Yes	aaabbb	The current version token for optimistic locking. Obtain this token by calling the `GetTableMetadataLocation` or `GetTable` operation. This parameter is in the request body.
metadataLocation	String	Yes	oss://data-bucket/metadata/00001-xxx.metadata.json	The OSS path to the new metadata file. Must point to a valid Iceberg metadata JSON file. This parameter is in the request body.

Response parameters

Parameter	Type	Example	Description
metadataLocation	String	oss://bucket/metadata/00000-xxx.metadata.json	The updated OSS path of the metadata file.
name	String	my_table	The name of the table.
namespace	Array	-	The namespace of the table, returned as an array.
tableARN	String	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id	The ARN of the table.
versionToken	String	abc123def456	The updated version token.

Examples

Request example

PUT /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace/my_table/metadata-location 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****

{
   "versionToken": "aaabbb",
   "metadataLocation": "oss://data-bucket/metadata/00001-xxx.metadata.json"
}

Response example

HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json


{
   "metadataLocation": "oss://data-bucket/metadata/00001-xxx.metadata.json",
   "name": "my_table",
   "namespace": ["my_namespace"],
   "tableARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id",
   "versionToken": "cccbbb"
}

SDKs

The following SDKs support the UpdateTableMetadataLocation operation:

ossutil CLI

For the corresponding ossutil command, see update-table-metadata-location.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	The request is invalid or malformed.
ForbiddenException	403	The caller lacks the required permissions to perform this operation.
NotFoundException	404	The requested resource does not exist.
ConflictException	409	The request conflicts with a previous write operation.