OpenMetaQuery-阿里云帮助中心

When you enable this feature, OSS creates a metadata index for the bucket and indexes all its objects. After the initial indexing, OSS performs near-real-time incremental scans to index new objects.

Usage notes

By default, an Alibaba Cloud account has the required permissions to enable metadata management. If you want to use a RAM user to enable this feature, you must grant the RAM user the oss:MetaQuery permission.
If you call this operation repeatedly on the same bucket, OSS returns the MetaQueryAlreadyExist error. To modify the configuration, you must first call the CloseMetaQuery operation and then call this operation again.
This is an asynchronous operation. After the call is successful, you can call the GetMetaQueryStatus operation to query the current status, retrieval mode, and effective configurations.
When you configure message notifications, you must grant the RAM role the permissions to access the specified MNS topic.
Advanced fields such as RouteRule, IndexOptions, and DatasetConfig take effect only when you use vector retrieval. If you include these fields in a call that uses scalar retrieval, OSS returns the InvalidArgument error.
You cannot modify RouteRule after you enable metadata management. You must decide whether to enable multi-dataset routing when you first call the OpenMetaQuery operation. To change this setting, you must first call CloseMetaQuery and then call this operation again. This clears all indexed metadata.
The WorkflowParameters parameter is for backward compatibility with basic workflow switches. This parameter does not support new AI content awareness features. We recommend using DatasetConfig for new integrations.

Request syntax

POST /?metaQuery&action=openMetaQuery&mode=semantic HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <Filters>
    <Filter>Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter>
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
  <NotificationAttributes>
    <Notifications>
      <Notification>
        <MNS>your-mns-topic-name</MNS>
      </Notification>
    </Notifications>
    <WithFields>
      <WithField>Insights</WithField>
    </WithFields>
  </NotificationAttributes>
  <DatasetConfig>
    <Insights>
      <Language>zh-Hans</Language>
      <Image>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Image>
      <Video>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Video>
    </Insights>
  </DatasetConfig>
  <IndexOptions>
    <IgnoreObjectDelete>True</IgnoreObjectDelete>
  </IndexOptions>
  <RouteRule>
    <Type>OSSTag</Type>
    <AutoCreateDataset>True</AutoCreateDataset>
    <OSSTagKey>routing-dataset</OSSTagKey>
  </RouteRule>
</MetaQuery>

Request headers

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

Request elements

Parameter	Type	Required	Example	Description
mode	String	Yes	basic	The retrieval mode. Valid values: basic (default): scalar retrieval semantic: vector retrieval
role	String	No	my-oss-role	The name of the RAM role used to access OSS. This parameter is required if you specify NotificationAttributes in the request.
MetaQuery	Container	No	N/A	The container for metadata query configurations. Child elements: WorkflowParameters, Filters, NotificationAttributes, DatasetConfig, IndexOptions, RouteRule
WorkflowParameters	Container	No	N/A	This parameter is for backward compatibility with basic switches for AI content awareness. This parameter does not support new features. We recommend using `DatasetConfig`. Parent element: MetaQuery Child element: WorkflowParameter
WorkflowParameter	Container	No	N/A	The container for a single workflow parameter. Parent element: WorkflowParameters
Name	String	No	VideoInsightEnable	The name of the workflow parameter. Valid values: VideoInsightEnable: Enables content awareness for videos. ImageInsightEnable: Enables content awareness for images. UserDefinedLabelsEnable: Enables user-defined labels.
Value	String	No	True	The value of the workflow parameter. Valid values: True: Enables the feature. False: Disables the feature.
Filters	Container	No	N/A	Supports logical operators (such as AND and OR) and comparison operators. You can specify a maximum of five OR and four AND conditions. Conditions in different Filter elements are combined by using the OR operator. Conditions separated by a comma (`,`) within a single Filter element are combined by using the AND operator. Child element: Filter Parent element: MetaQuery
Filter	String	No	Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z	A filter condition expression. For more information about the supported fields and comparison operators, see Appendix: Supported variables and operators for the Filters field. Parent element: Filters
NotificationAttributes	Container	No	N/A	This parameter configures notifications for object indexing. When object indexing is complete, OSS sends a notification to an MNS topic. Child elements: Notifications, WithFields Parent element: MetaQuery
Notifications	Container	No	N/A	The container for message notification configurations. Child element: Notification Parent element: NotificationAttributes
Notification	Container	No	N/A	The container for a single message notification configuration. Child element: MNS Parent element: Notifications
MNS	String	No	your-mns-topic-name	The name of the MNS topic. Parent element: Notification
WithFields	Container	No	N/A	The container that specifies the fields to be included in message notifications. Child element: WithField Parent element: NotificationAttributes
WithField	String	No	Insights	The fields to be included in the message notification. Valid values: Insights: A brief description of the object generated by AI analysis. Labels: The labels identified for the object by AI analysis. Parent element: WithFields
DatasetConfig	Container	No	N/A	Use this parameter to configure detailed settings for content awareness and intelligent grouping at the dataset level. For more information about the fields, see DatasetConfig data structure. Parent element: MetaQuery
IndexOptions	Container	No	N/A	The container for indexing options. This parameter controls how the metadata index responds to OSS object events. This parameter takes effect only when you use vector retrieval. Child elements: IgnoreObjectDelete, IgnoreEvents Parent element: MetaQuery
IgnoreObjectDelete	String	No	True	Valid values: True: If you delete an object, OSS does not automatically remove its metadata from the index. You must call the DeleteFileMeta operation to manually clear the metadata. False (default): When you delete an object, OSS also removes its metadata. Parent element: IndexOptions
IgnoreEvents	Container	No	N/A	A list of OSS event types to ignore. This is a low-level, fine-grained configuration. In most cases, IgnoreObjectDelete is sufficient. Child element: IgnoreEvent Parent element: IndexOptions
IgnoreEvent	String	No	ObjectRemoved:*	The OSS event type to ignore. Parent element: IgnoreEvents
RouteRule	Container	No	N/A	The container for the routing rule. This parameter enables the multi-dataset feature. It routes the metadata of different objects to different datasets based on their OSS object tags. This parameter takes effect only when you use vector retrieval. Child elements: Type, AutoCreateDataset, OSSTagKey Parent element: MetaQuery
Type	String	Yes (if RouteRule is used)	OSSTag	The routing type. Valid values: default: Routing rules are not applied. All metadata is routed to the system default dataset. OSSTag: Routes objects to a dataset whose name matches the value of a specified tag. Parent element: RouteRule
AutoCreateDataset	String	No	True	Specifies whether to automatically create a dataset if the dataset specified by the OSS tag does not exist. Valid values: True and False. Default value: False. Parent element: RouteRule
OSSTagKey	String	Yes (if Type is OSSTag)	routing-dataset	The key of the OSS object tag to use for routing. The tag's value on an object determines the destination dataset's name. Parent element: RouteRule

Response headers

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

Examples

Request examples

We recommend using DatasetConfig to configure the new content awareness features:

POST /?metaQuery&action=openMetaQuery&mode=semantic 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>
  <Filters>
    <Filter>Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter>
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
  <NotificationAttributes>
    <Notifications>
      <Notification>
        <MNS>your-mns-topic-name</MNS>
      </Notification>
    </Notifications>
    <WithFields>
      <WithField>Insights</WithField>
    </WithFields>
  </NotificationAttributes>
  <DatasetConfig>
    <Insights>
      <Language>zh-Hans</Language>
      <Image>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Image>
      <Video>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Video>
    </Insights>
  </DatasetConfig>
  <RouteRule>
    <Type>OSSTag</Type>
    <AutoCreateDataset>True</AutoCreateDataset>
    <OSSTagKey>routing-dataset</OSSTagKey>
  </RouteRule>
</MetaQuery>

The following is a backward-compatible example of WorkflowParameters. This approach is used only for legacy basic switches, and new features will no longer be implemented through WorkflowParameters:

POST /?metaQuery&action=openMetaQuery&mode=semantic 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>ImageInsightEnable</Name>
      <Value>True</Value>
    </WorkflowParameter>
    <WorkflowParameter>
      <Name>VideoInsightEnable</Name>
      <Value>True</Value>
    </WorkflowParameter>
  </WorkflowParameters>
</MetaQuery>

Response example

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Thu, 17 Apr 2025 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

MNS message notification format

If you configure message notification parameters, OSS sends a notification to the MNS topic when object indexing is complete. The following code shows the notification 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",
            "Insights": {
                "Video": {
                    "Caption": "A static view of an indoor corner",
                    "Description": "This is an indoor scene with a split view. The left side shows a glass door with a white curtain, with a blurry outdoor view visible. The right side shows a corner with a brown leather sofa, a gray chair, and a wooden cabinet."
                }
            }
        }
    ],
    "UserData": ""
}

Appendix: Variables and operators for Filters

Parameter	Type	Supported operators	Description	Filter example
Size	Integer	=: Equals (same as ==) !=: Not equal to >: Greater than >=: Greater than or equal to <: Less than <=: Less than or equal to	Filters objects by size.	Size > 9: The object size is greater than 9 bytes.
Filename	String	=: Equals (same as ==) !=: Not equal to prefix: Contains the prefix suffix: Contains the suffix in: Is in the set notin: Is not in the set	Filters objects by name. The object name must be Base64-encoded in a URL-safe format.	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	=: Equals (same as ==) !=: Not equal to >: Greater than >=: Greater than or equal to <: Less than <=: Less than or equal to	Filters objects by modification time. The time must be in the RFC3339Nano format.	FileModifiedTime > 2025-06-03T09:20:47.999Z: The object was modified after 2025-06-03T09:20:47.999Z.
OSSTagging.*	String	=: Equals (same as ==) !=: Not equal to !: The key does not exist exists: The key exists prefix: Contains the prefix suffix: Contains the suffix in: Is in the set notin: Is not in the set	Filters objects by tag. The tag key and value must be Base64-encoded in a URL-safe format.	OSSTagging.Zm9v == YWJj: The object has a tag with the key `foo` and the value `abc`. !OSSTagging.Zm9v: The object does not have a tag with the key `foo`. OSSTagging.Zm9v: The object has a tag with the key `foo`. The `exists` keyword is not required. OSSTagging.Zm9v in (YWJj, ZWZn): The object has a tag with the key `foo` and a value of `abc` or `efg`. OSSTagging.Zm9v prefix (YWEvYmIv, YWEvY2Mv): The object has a tag with the key `foo` and a value that has the prefix `aa/bb/` or `aa/cc/`.