OpenMetaQuery-阿里云帮助中心

Call the OpenMetaQuery operation to enable the Data Management feature for a bucket and select a retrieval mode. After the feature is enabled, OSS creates a metadata index library for the bucket and builds indexes for all objects in it. OSS then performs Near Real-Time incremental scans to index new objects.

Notes

By default, an Alibaba Cloud account has the permission to enable the Data Management feature. If you want to use a Resource Access Management (RAM) user to enable the feature, you must ensure that the RAM user is granted the oss:OpenMetaQuery permission. For more information, see Grant custom access policies to a RAM user.
For more information about data indexes, see Data indexes.

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>
  <Filters>
    <Filter>filter1</Filter>
    <Filter>filter2</Filter>
  </Filters>
</MetaQuery>

Request headers

Name

Type

Required

Example

Description

mode

String

Yes

basic

The retrieval mode. Valid values:

basic (default): Scalar retrieval
semantic: Semantic search

Request elements

Name	Type	Required	Example	Description
MetaQuery	Container	No	None	The container for the metadata query. Child node: Filters
Filters	Container	No	None	The container for filter conditions. It supports logical operations such as AND and OR, and comparison operators. The logical relationship between `Filter` expressions is OR. In a single `Filter` expression, multiple conditions are separated by commas (`,`) and have a logical AND relationship. The following example filters for objects that are larger than 1024 bytes and were modified after 2025-06-03T09:20:47.999Z, or objects whose prefixes are `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 the supported fields and comparison operators, see Appendix: Supported 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

Response headers

The response contains only 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>
  <Filters>
    <Filter>Size > 1024, FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter>
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
</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-server-time: 544

SDK

The following software development kits (SDKs) are available for this operation:

ossutil command-line tool

For the ossutil command for the OpenMetaQuery operation, see open-meta-query.

Appendix: Supported variables and operators for the Filters field

Name	Type	Supported operators	Description	Filter example
Size	Integer	`=`: Equal to. This is the same as `==`. `!=`: 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.
Filename	String	`=`: Equal to (equivalent to `==`) `!=`: Not equal to `prefix`: Contains the prefix `suffix`: Contains the suffix `in`: Is in the collection `notin`: Is not in the 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 prefix is `aa/bb/` or `aa/cc/`. `Filename suffix`: The file extension. Valid values are .jpg and .png.
FileModifiedTime	String	`=`: Equals. This is 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 RFC 3339 time format.	`FileModifiedTime > 2025-06-03T09:20:47.999Z`: The object was modified after 2025-06-03T09:20:47.999Z.
OSSTagging.*	String	`=`: Equal to, which is equivalent to `==`. `!=`: Not equal to `!`: The key does not exist `exists`: The key exists `prefix`: Contains the prefix `suffix`: Contains the suffix `in`: Is in the collection `notin`: Is not in the 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 Do not use the exists keyword. Specify only the key. `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/`.