OpenMetaQuery

Notes

By default, an Alibaba Cloud account has permission to enable metadata management. To use a RAM user, grant the oss:OpenMetaQuery permission. Grant custom permissions to a RAM user.
Data indexing.

Request syntax

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 file filter conditions.
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
</MetaQuery>

Request headers

This operation uses only 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 RAM role name for accessing OSS. You can grant permissions to the role in the console to ensure secure access.
MetaQuery	Container	No	N/A	The container for metadata query. Child node: Filters
WorkflowParameters	Container	No	N/A	The container for workflow parameters. Configures AI content awareness features.
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: The switch for video content awareness. ImageInsightEnable: The switch for image content awareness.
Value	String	No	True	The value of the workflow parameter. True: Enables the feature. False: Disables the feature.
Filters	Container	No	N/A	The container for filter conditions. Supports both AND and OR logical operations with comparison operators. Maximum: 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. Example: filter files larger than 1024 bytes modified after 2025-06-03T09:20:47.999Z, or files with 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. Supported fields and operators are listed in Appendix: Variables and operators supported by the Filters field. The example value filters for files 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-request-id: 5C06A3B67B8B5A3DA422299D
x-oss-server-time: 544

SDK

Supported SDKs:

ossutil

The corresponding ossutil command is open-meta-query.

Appendix: Variables and operators supported by the Filters field

Name	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 file size.	`Size > 9`: The file size is greater than 9.
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 filename. The filename must be URL-safe Base64 encoded.	`Filename == YWEvYmIvY2MuanBn` : The filename is `aa/bb/cc.jpg`. `Filename != YWEvYmIvY2MuanBn`: The filename is not `aa/bb/cc.jpg`. `Filename notin (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn)`: The filename is not `aa/bb/cc.jpg` or `aa/bb/dd.jpg`. `Filename in (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn`: The filename is `aa/bb/cc.jpg` or `aa/bb/dd.jpg`. `Filename prefix (YWEvYmIv, YWEvY2Mv)`: The filename prefix is `aa/bb/` or `aa/cc/`. `Filename suffix (LmpwZw, LnBuZw)`: The filename suffix is `.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 file modification time. Use the RFC3339Nano time format.	`FileModifiedTime > 2025-06-03T09:20:47.999Z`: The file 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 You do not need to use the `exists` keyword. Just specify 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/`.