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

Configures automatic maintenance for a specified table. Supported maintenance types: icebergCompaction, which merges small files to improve query performance, and icebergSnapshotManagement, which deletes expired snapshots to reduce storage overhead.

Usage notes

You can configure only one maintenance type per call.

Permissions

API	Action	Description
PutTableMaintenanceConfiguration	oss:PutTableMaintenanceConfiguration	Sets the table maintenance configuration and checks the table policy.

Request syntax

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

{
   "value": {
      "status": "string",
      "settings": {
         "icebergCompaction": {
            "targetFileSizeMB": number,
            "strategy": "string"
         }
      }
   }
}

Request parameters

Parameter	Type	Required	Example	Description
tableBucketARN	string	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	The Alibaba Cloud Resource Name (ARN) of the table bucket. The format is `acs:osstables:{region}:{uid}:bucket/{bucketName}`.
namespace	string	Yes	my_namespace	The name of the table's namespace.
name	string	Yes	my_table	The table name.
type	string	Yes	icebergCompaction	The maintenance type. Valid values: `icebergCompaction` (Iceberg table compaction) or `icebergSnapshotManagement` (Iceberg snapshot management).
value	container	Yes	-	A container for the maintenance configuration. Parent node: None Child nodes: status, settings
status	string	No	enabled	The status of the maintenance configuration. Valid values: `enabled` or `disabled`. Parent node: value
settings	container	No	-	A container for the configuration parameters. Parent node: value Child nodes: icebergCompaction, icebergSnapshotManagement
icebergCompaction	container	No	-	Iceberg table compaction configuration. Parent node: settings Child nodes: targetFileSizeMB, strategy
targetFileSizeMB	integer	No	100	The target file size in MB after compaction. The value must be an integer from 1 to 2,147,483,647. Parent node: icebergCompaction
strategy	string	No	auto	The compaction strategy. Valid values: `auto`, `binpack`, `sort`, or `z-order`. Parent node: icebergCompaction
icebergSnapshotManagement	container	No	-	Iceberg snapshot management configuration. Parent node: settings Child nodes: minSnapshotsToKeep, maxSnapshotAgeHours
minSnapshotsToKeep	integer	No	3	The minimum number of snapshots to retain. The value must be an integer from 1 to 2,147,483,647. Parent node: icebergSnapshotManagement
maxSnapshotAgeHours	integer	No	72	The maximum age of a snapshot in hours before it is eligible for deletion. The value must be an integer from 1 to 2,147,483,647. Parent node: icebergSnapshotManagement

Examples

Example 1: Configure Iceberg table compaction

Request sample

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

{
   "value": {
      "status": "enabled",
      "settings": {
         "icebergCompaction": {
            "targetFileSizeMB": 100,
            "strategy": "auto"
         }
      }
   }
}

Response sample

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

Example 2: Configure Iceberg snapshot management

Request sample

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

{
   "value": {
      "status": "enabled",
      "settings": {
         "icebergSnapshotManagement": {
            "minSnapshotsToKeep": 3,
            "maxSnapshotAgeHours": 72
         }
      }
   }
}

Response sample

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

SDKs

The following SDKs support this operation:

ossutil CLI

The corresponding ossutil command is put-table-maintenance-configuration.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	The request is invalid or malformed.
ForbiddenException	403	You do not have permission to perform this request.
NotFoundException	404	The requested resource does not exist.