All Products
Search

This Product

    Object Storage Service:DoMetaQuery

    Document Center

    Object Storage Service:DoMetaQuery

    Last Updated:Apr 28, 2024

    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 HTTP 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 HTTP 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 qn6qn6q**************:77Dv****************ml 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.