Use OpenMetaQuery to enable metadata indexing for a bucket - Object Storage Service

Call the OpenMetaQuery operation to enable the metadata management feature for a bucket and select a retrieval mode. After you enable this feature, Object Storage Service (OSS) creates a metadata index library for the bucket. OSS then builds metadata indexes for all objects in the bucket. After the index library is created, OSS performs Near Real-Time incremental scans to track and build indexes for new objects.

Notes

By default, an Alibaba Cloud account has the permission to enable the metadata management feature. If you want to use a Resource Access Management (RAM) user to enable this feature, make sure that the RAM user is granted the oss:OpenMetaQuery permission. For more information, see Grant custom permissions to a RAM user.
For more information about data indexing, see Data indexing.

Request syntax

POST /?metaQuery&comp=add&mode=basic HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<MetaQuery>
  <WorkflowParameters>
   <WorkflowParameter>
	<Name>VideoInsightEnable</Name> 
	<Value>True</Value>  // Specifies whether to enable video content awareness.
   </WorkflowParameter>
   <WorkflowParameter>
	<Name>ImageInsightEnable</Name>
	<Value>True</Value>  // Specifies whether to enable image content awareness.
   </WorkflowParameter>
 </WorkflowParameters>
  <Filters>
    <Filter>Size > 1024, FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter> // Configures the filter conditions.
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
  <NotificationAttributes>
    <Notifications>
        <Notification>
            <MNS>your-mns-topic-name</MNS> // The name of the MNS topic.
        </Notification>
    </Notifications>
    <WithFields>
        <WithField>Insights</WithField> // The fields to be returned in the MNS message. The only valid value is Insights. If you do not specify this element, these fields are not returned.
    </WithFields>
  </NotificationAttributes>
</MetaQuery>

Request headers

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

Request elements

Name	Type	Required	Example	Description
mode	String	Yes	basic	The retrieval mode. Valid values: basic (default): Scalar search semantic: Semantic search
role	String	No	my-oss-role	The name of the RAM role used to access OSS. To ensure secure access, grant the necessary permissions to this role in the console. This parameter is required if you specify `NotificationAttributes` in the request.
MetaQuery	container	No	N/A	The container for the metadata query. Child nodes: Filters, NotificationAttributes
WorkflowParameters	container	No	N/A	Container for workflow parameters used to configure AI-powered content awareness.
WorkflowParameter	container	No	N/A	The container for a single workflow parameter. Parent node: WorkflowParameters
Name	String	No	VideoInsightEnable	The name of the workflow parameter. VideoInsightEnable: Enables video content awareness. ImageInsightEnable: Enables image content awareness.
Value	String	No	True	The value of the workflow parameter. True: Enables the specified feature. False: Disables the specified feature.
Filters	container	No	N/A	The container for filter conditions. It supports logical operators (AND and OR) and comparison operators. You can specify a maximum of five OR operations and four AND operations. The `Filter` expressions have an OR relationship with each other. In a single `Filter` expression, multiple conditions are separated by commas (`,`) and have an AND relationship. For example, to filter for objects that are larger than 1024 bytes and were modified after 2025-06-03T09:20:47.999Z, or objects that have the prefix 'aa/bb/' (YWEvYmIv is the URL-safe Base64 encoding of 'aa/bb/'). `<Filters> <Filter>Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter> <Filter>Filename prefix (YWEvYmIv)</Filter> </Filters>` Child node: Filter Parent node: MetaQuery
Filter	String	No	`Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z`	The filter condition expression. For information about supported variables and operators, see Appendix: Variables and operators for the Filters field. The example value filters for objects that are larger than 1024 bytes and were modified after 2025-06-03T09:20:47.999Z. Parent node: Filters
NotificationAttributes	container	No	N/A	Container for notification settings used to configure notifications that are sent to an MNS topic after the indexing of an object is complete. Child nodes: Notifications, WithFields Parent node: MetaQuery
Notifications	container	No	N/A	The container for notification configurations. Child node: Notification Parent node: NotificationAttributes
Notification	container	No	N/A	Child node: MNS Parent node: Notifications
MNS	String	No	ipc-test-oss-notification	The name of the MNS topic. Parent node: Notification
WithFields	container	No	N/A	The container for specifying the fields to be returned in the notification message. Child node: WithField Parent node: NotificationAttributes
WithField	String	No	Insights	The field to be returned in the notification message. Valid value: Insights: A brief description of the object generated by AI analysis. Parent node: WithFields

Response headers

All headers in the response to a DescribeRegions request are common response headers. For more information, see Common response headers.

Examples

Request example

POST /?metaQuery&comp=add&mode=basic HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 13:08:38 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<MetaQuery>
  <WorkflowParameters>
   <WorkflowParameter>
	<Name>VideoInsightEnable</Name> 
	<Value>True</Value>  // Specifies whether to enable video content awareness.
   </WorkflowParameter>
   <WorkflowParameter>
	<Name>ImageInsightEnable</Name>
	<Value>True</Value>  // Specifies whether to enable image content awareness.
   </WorkflowParameter>
 </WorkflowParameters>
  <Filters>
    <Filter>Size > 1024, FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter> // Configures filter conditions: The object size is greater than 1024 bytes and the object was modified after 2025-06-03T09:20:47.999Z. 
    <Filter>Filename prefix (YWEvYmIv)</Filter>  // Configures a prefix filter: The prefix is YWEvYmIv, which is the Base64 encoding of the path aa/bb/.
  </Filters>
  <NotificationAttributes>
    <Notifications>
        <Notification>
            <MNS>your-mns-topic-name</MNS> // The name of the MNS topic.
        </Notification>
    </Notifications>
    <WithFields>
        <WithField>Insights</WithField> // Specifies the fields to return in the MNS message. Valid value: Insights. If omitted, these fields are not returned.
    </WithFields>
  </NotificationAttributes>
</MetaQuery>

Response example

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
x-oss-server-time: 544

MNS notification format

If you configure notification parameters, OSS sends a notification to the specified MNS topic after indexing each object. The notification is in the following format:

{
      "DatasetName": "your_dataset",
      "RequestId": "EC8CC942-BA82-BC29-BB5E-3F193F9964CE",
      "StartTime": "2026-02-27T19:20:35.190142739+08:00",
      "EndTime": "2026-02-27T19:21:44.021599314+08:00",
      "Success": true,
      "Message": "",
      "Files": [
          {
              "URI": "oss://your_bucket/dir/test.mp4",
              "Error": "",
              "ObjectStatus": "Indexed",
              "SequenceNumber": 4,
              "Insights": {
                  "Video": {
                      "Caption": "Indoor corner static scene",
                      "Description": "This is an indoor scene. The frame is split into left and right views: on the left is a glass door with white curtains, with a faint, blurry outdoor view beyond it. On the right is a corner area with a brown leather sofa, a gray chair, and a wooden cabinet. Next to the sofa is a black stroller and a green potted plant. A bright yellow ball sits on top of the cabinet."
                  }
              }
          }
      ],
      "UserData": ""
  }

SDK

You can call this operation using the following SDKs:

ossutil command-line interface

For information about the ossutil command that corresponds to the OpenMetaQuery operation, see open-meta-query.

Appendix: Variables and operators for the Filters field

Parameter	Type	Supported operators	Description	Filter example
Size	Integer	`=`: Equal to. Equivalent to `==`. `!=`: Not equal to `>`: Greater than `>=`: Greater than or equal to `<`: Less than `<=`: Less than or equal to	Filters by object size.	`Size > 9`: The object size is greater than 9 bytes.
Filename	String	`=`: Equal to. Equivalent to `==`. `!=`: Not equal to `prefix`: Contains prefix `suffix`: Contains suffix `in`: In a collection `notin`: Not in a collection	Filters by object name. The object name must be URL-safe Base64 encoded.	`Filename == YWEvYmIvY2MuanBn` : The object name is 'aa/bb/cc.jpg'. `Filename != YWEvYmIvY2MuanBn`: The object name is not 'aa/bb/cc.jpg'. `Filename notin (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn)`: The object name is not 'aa/bb/cc.jpg' or 'aa/bb/dd.jpg'. `Filename in (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn`: The object name is 'aa/bb/cc.jpg' or 'aa/bb/dd.jpg'. `Filename prefix (YWEvYmIv, YWEvY2Mv)`: The object name has the prefix 'aa/bb/' or 'aa/cc/'. `Filename suffix (LmpwZw, LnBuZw)`: The object name has the suffix '.jpg' or '.png'.
FileModifiedTime	String	`=`: Equal to. Equivalent to `==`. `!=`: Not equal to `>`: Greater than `>=`: Greater than or equal to `<`: Less than `<=`: Less than or equal to	Filters by object modification time. Use the RFC3339Nano time format.	`FileModifiedTime > 2025-06-03T09:20:47.999Z`: The object was modified after 2025-06-03T09:20:47.999Z.
OSSTagging.*	String	`=`: Equal to. Equivalent to `==`. `!=`: Not equal to `!`: Key does not exist `exists`: Key exists `prefix`: Contains prefix `suffix`: Contains suffix `in`: In a collection `notin`: Not in a collection	Filters by tag. The tag key and value must be URL-safe Base64 encoded.	`OSSTagging.Zm9v == YWJj`: The tag key is 'foo' and its value is 'abc'. `!OSSTagging.Zm9v`: The tag key 'foo' does not exist. `OSSTagging.Zm9v`: The tag key 'foo' exists. Note To check for the existence of a key, specify only the key. The `exists` keyword is not required. `OSSTagging.Zm9v in (YWJj, ZWZn)`: The tag key is 'foo' and its value is 'abc' or 'efg'. `OSSTagging.Zm9v prefix (YWEvYmIv, YWEvY2Mv)`: The tag key is 'foo' and its value has the prefix 'aa/bb/' or 'aa/cc/'.