DoMetaQuery - Object Storage Service - Alibaba Cloud Documentation Center

Queries objects that meet specified conditions and lists the information about objects based on specified fields and sorting methods. You can also use nested queries to implement complex queries and perform aggregate operations to collect and analyze the values of different fields.

Usage notes

To query objects that meet specified conditions, you must have the oss:DoMetaQuery permission. For more information, see Attach a custom policy to a RAM user.

Request syntax

POST /?metaQuery&comp=query HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue 
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken></NextToken>
  <MaxResults>5</MaxResults>
  <Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
  <Sort>Size</Sort>
  <Order>asc</Order>
  <Aggregations>
    <Aggregation>
      <Field>Size</Field>
      <Operation>sum</Operation>
    </Aggregation>
    <Aggregation>
      <Field>Size</Field>
      <Operation>max</Operation>
    </Aggregation>
  </Aggregations>
</MetaQuery>

Request headers

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

Request elements


Element	Type	Required	Example	Description
MetaQuery	Container	Yes	N/A	The container for query conditions. Child nodes: NextToken, MaxResults, Query, Sort, Order, and Aggregations
NextToken	String	No	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****	The token that is used for the next query when the total number of objects exceeds the value of MaxResults. The object information is returned in alphabetical order starting from the value of NextToken. When this operation is called for the first time, set this field to null. Parent nodes: MetaQuery
MaxResults	Integer	No	5	The maximum number of objects to return. Valid values: 0 to 100. If this parameter is not set or is set to 0, 100 objects are returned. Parent nodes: MetaQuery
Query	String	Yes	{"Field": "Size","Value": "1048576","Operation": "gt"}	The query condition. Options: Operation: the operators. Valid values: eq (equal to), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), match (fuzzy query), prefix (prefix query), and (AND), or (OR), and not (NOT). Field: the fields. For more information about supported fields and supported operators, see Appendix: Supported fields and operators. Value: the value of the field. SubQueries: the subquery conditions. Options that are included in this element are the same as those of simple query. You must set subquery conditions only when Operation is set to AND, OR, or NOT. For more information, see Query examples. Parent nodes: MetaQuery
Sort	String	No	Size	The field based on which the results are sorted. For more information about the fields that can be sorted, see Appendix: Supported fields and operators. Parent nodes: MetaQuery
Order	String	No	asc	The order in which you want to sort the queried data. Default value: desc. Valid values: asc: The data is sorted in ascending order desc: The data is sorted in descending order. Parent nodes: MetaQuery
Aggregations	Container	No	N/A	The container for the information about aggregate operations. Child nodes: Aggregation Parent nodes: MetaQuery
Aggregation	Container	No	N/A	The container for the information about a single aggregate operation. Child nodes: Field and Operation Parent nodes: Aggregations
Field	String	No	Size	The name of the field. For more information about supported fields and supported operators, see Appendix: Supported fields and operators. Parent nodes: Aggregation
Operation	String	No	sum	The operator for aggregate operations. Valid values: min max average sum count distinct group Parent nodes: Aggregation

Response headers

This request contains only common response headers. For more information, see Common response headers.

Response elements


Element	Type	Example	Description
MetaQuery	Container	N/A	The container for the query result. Child nodes: NextToken, Files, and Aggregations
NextToken	String	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****	The token that is used for the next query when the total number of objects exceeds the value of MaxResults. The value of NextToken is used to return the unreturned results in the next query. This parameter has a value only when not all objects are returned. Parent nodes: MetaQuery
Files	Container	N/A	The container for the information about objects. Child nodes: File Parent nodes: MetaQuery
File	Container	N/A	The container for the information about a single object. Child nodes: Filename, Size, FileModifiedTime, OSSOobjectType, OSSStorageClass, ObjectACL, ETag, OSSTaggingCount, OSSTagging, OSSUserMeta, OSSCRC64, and ServerSideEncryption Parent nodes: Files
Filename	String	exampleobject.txt	The full path of the object. Parent nodes: File
Size	Integer	120	The size of the object. Unit: bytes. Parent nodes: File
FileModifiedTime	String	2021-06-29T15:04:05.000000000Z07:00	The time when the object was last modified. The value follows the RFC 3339 format. Parent nodes: File
OSSObjectType	String	Normal	The type of the object. Valid values: Normal: The object was uploaded by calling the PutObject operation or created by calling the CreateDirectory operation. Appendable: The object was uploaded by calling the AppendObject operation. Multipart: The object was uploaded by calling the MultipartUpload operation. Symlink: The symbolic link was created by calling the PutSymlink operation. Parent nodes: File
OSSStorageClass	String	Standard	The storage class of the object. Valid values: Standard: The Standard storage class provides highly reliable, highly available, and high-performance object storage services that can handle frequent data access. IA: The Infrequent Access (IA) storage class is suitable for long-term storage of data that is infrequently accessed. Data that is accessed once or twice per month on average falls into this class. Archive: The Archive storage class is suitable for long-term storage of data that is infrequently accessed. Data that you want to store for at least six months falls into this class. The data requires up to 1 minute to restore before you can read the data. ColdArchive: The Cold Archive storage class is suitable for long-term storage of data that is rarely accessed. Parent nodes: File
ObjectACL	String	default	The access control list (ACL) of the object. Valid values: default: The ACL of the object is the same as that of the bucket in which the object is stored. private: The ACL of the object is private. Only the owner of the object and authorized users have read and write permissions on the object. public-read: The ACL of the object is public read. Only the owner of the object and authorized users have read and write permissions on the object. Other users can only read the object. Exercise caution when you set the object ACL to this value. public-read-write: The ACL of the object is public read/write. All users have read and write permissions on the object. Exercise caution when you set the object ACL to this value. Parent nodes: File
ETag	String	"fba9dede5f27731c9771645a3986****"	The ETag that was generated when the object was created. ETags are used to identify the content of objects. If an object is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content. If an object is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value that is calculated based on a specific rule. Note The ETag value of an object can be used to check whether the object content is modified. We recommend that you use the MD5 hash of an object rather than the ETag value to check data integrity. Parent nodes: File
OSSTaggingCount	Integer	2	The number of tags of the object. Parent nodes: File
OSSTagging	Container	N/A	The container for the information about the tags. Child nodes: Tagging Parent nodes: File
Tagging	Container	N/A	The container for the information about a single tag. Child nodes: Key and Value. Parent nodes: OSSTagging
Key	String	owner	The key of the tag or user metadata. User metadata must be prefixed with `x-oss-meta-`. Parent nodes: Tagging and UserMeta
Value	String	John	The value of the tag or user metadata. Parent nodes: Tagging and UserMeta
OSSUserMeta	Container	N/A	The container for user metadata. Child nodes: UserMeta Parent nodes: File
UserMeta	Container	N/A	The container for the metadata of a single user. Child nodes: Key and Value. Parent nodes: OSSUserMeta
OSSCRC64	String	4858A48BD1466884	The CRC-64 value of the object. This value is calculated based on the ECMA-182 standard.
ServerSideEncryption	String	AES256	The server-side encryption algorithm used when Object Storage Service (OSS) created the object. Valid value: AES256. Parent nodes: File
ServerSideEncryptionCustomerAlgorithm	String	SM4	The algorithm that is used to encrypt the object on a local client. Parent nodes: File
Aggregations	Container	N/A	The container for the information about aggregate operations. Child nodes: Field, Operation, Value, and Groups Parent nodes: MetaQuery
Field	String	Size	The name of the field. Parent nodes: Aggregations
Operation	String	sum	The operator for the aggregate operation. Parent nodes: Aggregations
Value	Float	200	The result of the aggregate operation. Parent nodes: Aggregations
Groups	Container	N/A	The result list of aggregation operations performed by group. Child nodes: Value and Count Parent nodes: Aggregations
Value	String	100	The result of the aggregation operations performed by group. Parent nodes: Groups
Count	Integer	5	The number of aggregation operations performed by group. Parent nodes: Groups

Examples

Sample requests

POST /?metaQuery&comp=query HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 26 Jul 2021 13:08:38 GMT
Authorization: OSS qn6qrrqxo2oawuk53otf****:ceOEyZavKY4QcjoUWYSpYbJ3****
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****</NextToken>
  <MaxResults>5</MaxResults>
  <Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
  <Sort>Size</Sort>
  <Order>asc</Order>
  <Aggregations>
    <Aggregation>
      <Field>Size</Field>
      <Operation>sum</Operation>
    </Aggregation>
    <Aggregation>
      <Field>Size</Field>
      <Operation>max</Operation>
    </Aggregation>
  </Aggregations>
</MetaQuery>

Sample responses

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****</NextToken>
  <Files>
    <File>
      <Filename>exampleobject.txt</Filename>
      <Size>120</Size>
      <FileModifiedTime>2021-06-29T15:04:05.000000000Z07:00</FileModifiedTime>
      <OSSObjectType>Normal</OSSObjectType>
      <OSSStorageClass>Standard</OSSStorageClass>
      <ObjectACL>default</ObjectACL>
      <ETag>"fba9dede5f27731c9771645a3986****"</ETag>
      <OSSCRC64>4858A48BD1466884</OSSCRC64>
      <OSSTaggingCount>2</OSSTaggingCount>
      <OSSTagging>
        <Tagging>
          <Key>owner</Key>
          <Value>John</Value>
        </Tagging>
        <Tagging>
          <Key>type</Key>
          <Value>document</Value>
        </Tagging>
      </OSSTagging>
      <OSSUserMeta>
        <UserMeta>
          <Key>x-oss-meta-location</Key>
          <Value>hangzhou</Value>
        </UserMeta>
      </OSSUserMeta>
    </File>
  </Files>
</MetaQuery>

Query examples

Queries can be nested. You can use nested queries to implement complex queries and exact match. The following examples show how to perform nested queries.

If you want to query an object whose name is exampleobject.txt and whose size is less than 1,000 bytes, you can configure the query as shown in the following example:


{
  "SubQueries":[
    {
      "Field":"Filename",
      "Value": "exampleobject.txt",
      "Operation":"eq"
    },         
    {
      "Field":"Size",
      "Value":"1000",
      "Operation":"lt"
    }
  ],
  "Operation":"and"
}

If you want to query objects that are prefixed with exampledir/, contain the type=document or owner=John tag, and are larger than 10 MB in size, you can configure the query as shown in the following example:


{
  "SubQueries": [
    {
      "Field": "Filename",
      "Value": "exampledir/",
      "Operation": "prefix"
    },
    {
      "Field": "Size",
      "Value": "1048576",
      "Operation": "gt"
    },
    {
      "SubQueries": [
        {
          "Field": "OSSTagging.type",
          "Value": "document",
          "Operation": "eq"
        },
        {
          "Field": "OSSTagging.owner",
          "Value": "John",
          "Operation": "eq"
        }
      ],
      "Operation": "or"
    }
  ],
  "Operation": "and"
}

You can also perform aggregate operations to collect and analyze different data based on the preceding search conditions. For example, you can calculate the sum, count, average value, or maximum value of all objects that meet the query conditions. You can also calculate the size distribution of images that meet the query conditions.

Error codes


Error code	HTTP status code	Description
MetaQueryNotExist	400	The error message returned because the metadata index library does not exist in the bucket. Make sure that you have enabled the metadata management feature for the bucket and try again after the metadata index library is created.
EntityTooLarge	400	The error message returned because the maximum string size allowed for the query condition specified by the Query parameter has been exceeded. Modify the query condition and try again.
InvalidArgument	400	The error message returned because the specified argument value is invalid. Specify a valid argument.
InvalidParameter	400	The error message returned because the specified parameter value is invalid. Specify a valid parameter value.
MissingParameter	400	The error message returned because a required parameter in the request is not specified. Specify all the required parameters.
Throttling.Api	403	The error message returned because your request is denied due to throttling. Reduce the queries per second (QPS) of the request and try again. If the error persists after you try the operation multiple times, submit a ticket.
Throttling.User	403	The error message returned because your request is denied due to throttling. Reduce the queries per second (QPS) of the request and try again.If the error persists after you try the operation multiple times, submit a ticket.
AccessDenied	403	The error message returned because you do not have permissions to access the bucket. Make sure that the RAM user is granted permissions to access the bucket.
NoSuchBucket	404	The error message returned because the destination bucket does not exist. Specify a valid bucket name.
InternalServerError	500	The error message returned because an internal error has occurred.If the error persists after you try the operation multiple times, submit a ticket.