AI 助理
文档备案控制台
官方文档
首页

SimpleQuery

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

调用 SimpleQuery 接口在指定 Dataset 内对结构化元数据做条件查询、排序与聚合。功能与 DoMetaQuery 的 标量检索 等价,但需要在请求中显式指定 datasetName,适用于在 Bucket 含有多个 Dataset 时精确查询某一个 Dataset。

注意事项

  • 调用本接口的 RAM 用户需要 oss:MetaQuery 权限。

  • 调用本接口前,需先通过 OpenMetaQuery 开启元数据管理。

  • 本接口的所有参数都通过 URL Query String 传递,不接受 HTTP body。

  • query 是结构化查询条件对象,通过 URL Query String 传递时需 JSON 序列化并 URL 编码。本接口只有 query 一个查询字段,复合条件请用 SubQueries 嵌套表达;若需要在结果上做自然语言语义检索,请使用 SemanticQuery。

  • 本接口每次只查询 datasetName 指定的单个 Dataset,当前不支持跨 Dataset 检索。如需查询多个 Dataset,请分别调用本接口。

请求语法

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

请求头

此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。

请求元素

名称

类型

是否必选

示例值

描述

datasetName

字符串

是

photos-2026

要查询的 Dataset 名。

query

Query 对象

是

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

结构化查询条件。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。

子节点:Field、Operation、Value、SubQueries

Field

字符串

否

Size

字段名称。支持的字段以及字段对操作符的支持情况，请参见附录：标量检索的字段和操作符列表。

父节点:query

Operation

字符串

是

gt

操作符。取值见下方「操作符（Operation）取值说明」。

父节点:query

Value

字符串

否

1048576

字段值。比较、匹配、前缀查询等操作符需要设置。

父节点:query

SubQueries

Query 数组

否

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

子查询条件列表。仅当 Operation 为 and、or、not 时设置。

数组元素为 Query 对象(结构同 query,可递归嵌套)

父节点:query

sort

字符串

否

Size

排序字段名,常用 Size / FileModifiedTime。关于支持排序的字段列表，请参见附录：标量检索的字段和操作符列表。

order

字符串

否

desc

排序方向,仅在指定了 sort 时生效。取值如下:

  • asc：升序

  • desc：降序（默认值）

aggregations

Aggregation 数组

否

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

聚合配置。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。

子节点:Aggregation

Aggregation

容器

否

不涉及

单个聚合配置。

子节点:Field、Operation

父节点:aggregations

Field

字符串

是

Size

聚合字段名,如 Size / ContentType 等。关于支持的字段以及字段对操作符的支持情况，请参见附录：标量检索的字段和操作符列表。

父节点:Aggregation

Operation

字符串

是

sum

聚合算子。取值如下:

  • min：最小值

  • max：最大值

  • average：平均数

  • sum：求和

  • count：计数

  • distinct_count：去重统计

  • group_by：分组统计

父节点:Aggregation

withFields

字符串数组

否

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

投影字段列表。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。

子节点:WithField

WithField

字符串

否

URI

单个投影字段名,如 URI / Size / FileModifiedTime / Insights 等。

父节点:withFields

withoutTotalHits

布尔值

否

false

是否跳过总数统计。取值如下:

  • true：跳过统计,响应中 <TotalHits> 占位为 -1,大结果集分页时建议使用

  • false（默认值）：正常统计

maxResults

整型

否

100

单次返回的最大结果数,取值范围 1 到 100,默认 100。

nextToken

字符串

否

MTIzNDU2

分页令牌。首次请求不传;后续请求传入上次响应中的 <NextToken> 拉取下一页。

操作符（Operation）取值说明

类别

取值

说明

比较

eq / gt / gte / lt / lte

等于 / 大于 / 大于等于 / 小于 / 小于等于

文本

match

子串匹配

文本

prefix

前缀匹配

逻辑

and / or / not

逻辑组合,需配合 SubQueries 嵌套使用

响应头

此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。

响应元素

名称

类型

是否必选

示例值

描述

MetaQuery

容器

是

不涉及

检索结果的根容器。

子节点:Files、TotalHits、NextToken、Aggregations

Files

容器

否

不涉及

命中的文件列表容器。

子节点:File

父节点:MetaQuery

File

容器

否

不涉及

单个文件的元数据。完整字段见 File 数据结构。

父节点:Files

TotalHits

整型

否

128

命中总数。请求中设置 withoutTotalHits=true 时占位为 -1。

父节点:MetaQuery

NextToken

字符串

否

MTIzNDU2

下一页分页令牌。无更多结果时不出现。

父节点:MetaQuery

Aggregations

容器

否

不涉及

聚合结果容器。仅当请求中含 aggregations 参数时返回。

子节点:Aggregation

父节点:MetaQuery

Aggregation

容器

否

不涉及

单条聚合结果。

子节点:Field、Operation、Value、Groups

父节点:Aggregations

Field

字符串

否

Size

聚合字段名。

父节点:Aggregation

Operation

字符串

否

sum

聚合算子,与请求中的 Operation 对应。

父节点:Aggregation

Value

浮点型

否

268435456

聚合结果值。group_by 算子下不返回此字段。

父节点:Aggregation

Groups

容器

否

不涉及

分组统计结果列表容器,仅 Operation=group_by 时返回。

子节点:Group

父节点:Aggregation

Group

容器

否

不涉及

单个分组。

子节点:Value、Count

父节点:Groups

Value

字符串

否

image/jpeg

分组键的值。

父节点:Group

Count

整型

否

256

分组内的命中数。

父节点:Group

示例

请求示例

按结构化条件查询 photos-2026 Dataset 中 Size 大于 1 MB 的前 10 个文件:

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

URL 中 query 参数解码后为:

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

按标签精确查询命中标签为"有人摔倒"的文件:

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

URL 中 query 参数解码后为:

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

返回示例

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>夕阳下的海面,远处有几艘渔船。</Caption>
        </Image>
      </Insights>
      <Labels>
        <Label>
          <LabelName>夕阳</LabelName>
          <LabelConfidence>0.98</LabelConfidence>
        </Label>
      </Labels>
    </File>
  </Files>
</MetaQuery>
上一篇：CloseMetaQuery下一篇：SemanticQuery