DocsICP FilingConsole
官方文档
首页

SimpleQuery

更新时间：
复制 MD 格式
产品详情
我的收藏

The SimpleQuery operation performs conditional queries, sorting, and aggregations on structured metadata within a specified Dataset. This functionality is equivalent to the scalar search feature of the DoMetaQuery operation but requires you to specify datasetName in the request. This makes the operation ideal for querying a specific Dataset when a bucket contains multiple Datasets.

Usage notes

  • To call this operation, the RAM user must have the oss:MetaQuery permission.

  • Before you call this operation, you must enable metadata management by calling the OpenMetaQuery operation.

  • All parameters for this operation are passed in the URL query string. The request does not accept an HTTP body.

  • The query parameter is a structured query condition object that must be JSON serialized and then URL encoded when passed in the URL query string. To create compound conditions, use nested SubQueries within the query object. To perform a natural language semantic search on the results, use the SemanticQuery operation.

  • This operation queries only a single Dataset at a time, specified by datasetName. Cross-dataset search is not supported. To query multiple Datasets, you must call this operation separately for each Dataset.

Request syntax

POST /?metaQuery&action=simpleQuery&datasetName=DatasetName&query=Query&sort=Sort&order=Order&aggregations=Aggregations&withFields=WithFields&withoutTotalHits=WithoutTotalHits&maxResults=MaxResults&nextToken=NextToken HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

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

Request elements

Parameter

Type

Required

Example

Description

datasetName

string

Yes

photos-2026

The name of the Dataset to query.

query

Query object

Yes

{"Field":"Size","Operation":"gt","Value":"1048576"}

The structured query condition. When passed in the URL query string, the object must be JSON serialized and then URL encoded.

Child nodes: Field, Operation, Value, SubQueries

Field

string

No

Size

The name of the field. For a list of supported fields and their compatible operators, see Appendix: Fields and operators for scalar search.

Parent node: query

Operation

string

Yes

gt

The operator. For valid values, see "Operation values" below.

Parent node: query

Value

string

No

1048576

The field value. This parameter is required for operators such as comparison, match, and prefix match.

Parent node: query

SubQueries

Query array

No

[{"Field":"Size","Operation":"gt","Value":"1048576"}]

A list of subquery conditions. This parameter is used only when Operation is set to and, or, or not.

Each element in the array is a Query object that shares the same structure as query and can be nested.

Parent node: query

sort

string

No

Size

The sort field. Common fields include Size and FileModifiedTime. For a list of fields that support sorting, see Appendix: Fields and operators for scalar search.

order

string

No

desc

The sort order. This parameter applies only when sort is specified. Valid values:

  • asc: ascending order

  • desc: descending order (default)

aggregations

Aggregation array

No

[{"Field":"Size","Operation":"sum"}]

The aggregation configurations. When passed in the URL query string, the array must be JSON serialized and then URL encoded.

Child node: Aggregation

Aggregation

container

No

N/A

A single aggregation configuration.

Child nodes: Field, Operation

Parent node: aggregations

Field

string

Yes

Size

The field to aggregate, such as Size or ContentType. For a list of supported fields and their compatible operators, see Appendix: Fields and operators for scalar search.

Parent node: Aggregation

Operation

string

Yes

sum

The aggregation operator. Valid values:

  • min: The minimum value.

  • max: The maximum value.

  • average: The average of values.

  • sum: The sum of values.

  • count: The number of items.

  • distinct_count: The number of distinct values.

  • group_by: Groups items for statistical analysis.

Parent node: Aggregation

withFields

string array

No

["URI","Size","FileModifiedTime"]

A list of projection fields. When passed in the URL query string, the array must be JSON serialized and then URL encoded.

Child node: WithField

WithField

string

No

URI

A single projection field, such as URI, Size, FileModifiedTime, or Insights.

Parent node: withFields

withoutTotalHits

boolean

No

false

Specifies whether to skip counting the total hits. Valid values:

  • true: Skips the count. The <TotalHits> element in the response is a placeholder with a value of -1. This setting is recommended when you paginate through large result sets.

  • false (default): Performs the count.

maxResults

integer

No

100

The maximum number of results to return in a single response. The value must be in the range of 1 to 100. Default value: 100.

nextToken

string

No

MTIzNDU2

The pagination token. Do not specify this parameter for the first request. For subsequent requests, set this parameter to the value of <NextToken> from the previous response to retrieve the next page of results.

Operation values

Category

Value

Description

Comparison

eq / gt / gte / lt / lte

Equal to / Greater than / Greater than or equal to / Less than / Less than or equal to

Text

match

Substring match

Text

prefix

Prefix match

Logical

and / or / not

Logical combination. These operators must be used with nested SubQueries.

Response headers

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

Response elements

Parameter

Type

Required

Example

Description

MetaQuery

container

Yes

N/A

The root container for the query results.

Child nodes: Files, TotalHits, NextToken, Aggregations

Files

container

No

N/A

A container for the list of matched files.

Child node: File

Parent node: MetaQuery

File

container

No

N/A

The metadata for a single file. For the complete field reference, see File data structure.

Parent node: Files

TotalHits

integer

No

128

The total hits. If withoutTotalHits=true is set in the request, this element is a placeholder with a value of -1.

Parent node: MetaQuery

NextToken

string

No

MTIzNDU2

The pagination token for the next page of results. This element is not returned if there are no more results.

Parent node: MetaQuery

Aggregations

container

No

N/A

A container for the aggregation results. This element is returned only if the aggregations parameter is included in the request.

Child node: Aggregation

Parent node: MetaQuery

Aggregation

container

No

N/A

A single aggregation result.

Child nodes: Field, Operation, Value, Groups

Parent node: Aggregations

Field

string

No

Size

The name of the aggregated field.

Parent node: Aggregation

Operation

string

No

sum

The aggregation operator. This value corresponds to the Operation specified in the request.

Parent node: Aggregation

Value

float

No

268435456

The aggregated result value. This element is not returned for the group_by operator.

Parent node: Aggregation

Groups

container

No

N/A

A container for the list of grouped results. This element is returned only when Operation is set to group_by.

Child node: Group

Parent node: Aggregation

Group

container

No

N/A

A single group.

Child nodes: Value, Count

Parent node: Groups

Value

string

No

image/jpeg

The value of the grouping key.

Parent node: Group

Count

integer

No

256

The number of hits within the group.

Parent node: Group

Examples

Request examples

The following request queries for the first 10 objects in the photos-2026 Dataset that are larger than 1 MB:

POST /?metaQuery&action=simpleQuery&datasetName=photos-2026&query=%7B%22Field%22%3A%22Size%22%2C%22Operation%22%3A%22gt%22%2C%22Value%22%3A%221048576%22%7D&maxResults=10 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 09:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

The decoded query parameter in the URL is:

{"Field":"Size","Operation":"gt","Value":"1048576"}

Performing an exact-match query for files with the label "someone fell down":

POST /?metaQuery&action=simpleQuery&datasetName=videos-2026&query=%7B%22Field%22%3A%22Labels.LabelName%22%2C%22Operation%22%3A%22eq%22%2C%22Value%22%3A%22%E6%9C%89%E4%BA%BA%E6%91%94%E5%80%92%22%7D HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 09:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

The decoded query parameter in the URL is:

{"Field":"Labels.LabelName","Operation":"eq","Value":"有人摔倒"}

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F8
Date: Wed, 20 May 2026 09:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2</NextToken>
  <TotalHits>128</TotalHits>
  <Files>
    <File>
      <Filename>photos/sunset.jpg</Filename>
      <Size>2097152</Size>
      <FileModifiedTime>2026-05-19T15:30:00.000+08:00</FileModifiedTime>
      <ContentType>image/jpeg</ContentType>
      <ObjectACL>default</ObjectACL>
      <OSSStorageClass>Standard</OSSStorageClass>
      <ETag>"D41D8CD98F00B204E9800998ECF8427E"</ETag>
      <OSSTagging>
        <Tagging>
          <Key>routing-dataset</Key>
          <Value>photos-2026</Value>
        </Tagging>
      </OSSTagging>
      <Insights>
        <Image>
          <Caption>The sea surface at sunset, with several fishing boats in the distance.</Caption>
        </Image>
      </Insights>
      <Labels>
        <Label>
          <LabelName>Sunset</LabelName>
          <LabelConfidence>0.98</LabelConfidence>
        </Label>
      </Labels>
    </File>
  </Files>
</MetaQuery>
Previous：CloseMetaQueryNext：SemanticQuery