UpdateSmartCluster-阿里云帮助中心

Call UpdateSmartCluster to update the name, description, clustering rules, or message notification configuration of a SmartCluster.

Usage notes

By default, Alibaba Cloud accounts can update a SmartCluster. To call this operation as a RAM user, you must grant that user the oss:MetaQuery permission.
This operation is available only if multi-dataset routing is enabled by configuring the RouteRule parameter when calling the OpenMetaQuery operation.
You must specify at least one of the optional parameters: name, description, rules, or notification. Otherwise, the server returns an InvalidArgument error (HTTP 400).
If you update the rules parameter, the system retriggers clustering computation. During this process, the original clustering results are unavailable until the background recalculation completes.
The clustering type cannot be changed. To use a different type, you must delete the SmartCluster by calling DeleteSmartCluster and then create a new one by calling CreateSmartCluster.
The updated name must be unique within the dataset. Otherwise, the server returns a SmartClusterAlreadyExist error (HTTP 409).

Request syntax

POST /?metaQuery&action=updateSmartCluster&datasetName=DatasetName&objectId=ObjectId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Request elements

Parameter	Type	Required	Example	Description
datasetName	string	Yes	photos-2026	The name of the dataset where the SmartCluster is stored.
objectId	string	Yes	cluster-abc123def456	The unique ID of the SmartCluster.
name	string	No	face-cluster-alice-v2	The new name for the SmartCluster. The name must be unique within the dataset and up to 128 characters long.
description	string	No	Updated description	The new description, up to 128 characters long.
rules	array of SmartClusterRule	No	[{"RuleType":"face","BaseURIs":["oss://examplebucket/refs/alice2.jpg"]}]	The new array of clustering rules. When passed in a URL query string, this parameter must be a JSON-serialized and URL-encoded string. Updating this parameter retriggers clustering computation. child element: SmartClusterRule
SmartClusterRule	container	No	N/A	A single clustering rule. child elements: RuleType, BaseURIs, Keywords, and Sensitivity parent element: rules
RuleType	string	Yes	face	The type of the clustering rule. Valid values: face: Performs face clustering based on reference face images. This value must be used with a SmartCluster with a clusterType of figure. keywords: Performs semantic clustering based on keywords. This value must be used with a SmartCluster with a clusterType of knowledge. parent element: SmartClusterRule
BaseURIs	array of strings	No	["oss://examplebucket/refs/alice2.jpg"]	A list of OSS URIs for the reference objects in the format `oss://{bucket}/{key}`. This parameter is required when RuleType is set to face. You can specify up to three URIs. parent element: SmartClusterRule
Keywords	array of strings	No	["person","vehicle","building"]	A list of keywords for clustering. This parameter is required when RuleType is set to keywords. parent element: SmartClusterRule
Sensitivity	float	No	0.7	The sensitivity for clustering. The value must be in the range of [0, 1]. A higher value indicates a stricter match. parent element: SmartClusterRule
notification	notification object	No	{"MNS":{"TopicName":"imm-cluster-notification"}}	The new message notification configuration for Message Service (MNS). When passed in a URL query string, this parameter must be a JSON-serialized and URL-encoded string. child element: Notification
Notification	container	No	N/A	The message notification configuration for the clustering task. child element: MNS parent element: notification
MNS	container	No	N/A	The MNS notification configuration. child element: TopicName parent element: Notification
TopicName	string	No	imm-cluster-notification	The name of the MNS topic. parent element: MNS

Response headers

This operation uses only common response headers. For more information, see Common response headers.

Response elements

Parameter

Type

Required

Example

Description

UpdateSmartClusterResponse

container

Yes

N/A

The root element of the response.

child element: ObjectId

ObjectId

string

Yes

cluster-abc123def456

The unique ID of the updated SmartCluster. This value is the same as the objectId parameter in the request. You can use this value for idempotency checks.

parent element: UpdateSmartClusterResponse

Examples

Request example

POST /?metaQuery&action=updateSmartCluster&datasetName=photos-2026&objectId=cluster-abc123def456&description=Updated%20description HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 12:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F8
Date: Wed, 20 May 2026 12:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<UpdateSmartClusterResponse>
  <ObjectId>cluster-abc123def456</ObjectId>
</UpdateSmartClusterResponse>