调用 DoMetaQuery 接口在已开启元数据管理的 Bucket 默认 Dataset 上执行检索。支持两种模式:basic 模式按结构化属性(Size、Filename、FileModifiedTime、OSSTagging 等)做条件过滤、排序与聚合;semantic 模式按自然语言文本做向量相似度检索,并可附加结构化过滤条件。以图搜图相关参数作为预留参数保留,当前尚未支持。
注意事项
调用本接口的 RAM 用户需要
oss:MetaQuery权限。调用本接口前,需先通过 OpenMetaQuery 开启元数据管理。
mode必须与 OpenMetaQuery时设置的mode匹配。用basic打开的 Bucket 只能用 标量检索 查询;用semantic打开的 Bucket 可用basic或semantic查询。semantic模式不支持分页(响应无NextToken)、不支持聚合(请求中传入<Aggregations>不生效)。basic模式不支持<Filters>元素(<Filters>是OpenMetaQuery时配置的索引时过滤)。本接口只查询默认 Dataset。默认 Dataset 仅在 OpenMetaQuery不传
RouteRule时由系统创建和使用。若开启时配置了RouteRule,文件会按路由规则进入对应 Dataset;如需查询这些 Dataset,请使用 SimpleQuery 或 SemanticQuery并显式指定datasetName。
请求语法
标量检索
POST /?metaQuery&comp=query&mode=basic 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>向量检索
POST /?metaQuery&comp=query&mode=semantic HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
<MaxResults>99</MaxResults>
<Query>俯瞰白雪覆盖的森林</Query>
<MediaTypes>
<MediaType>image</MediaType>
</MediaTypes>
<SimpleQuery>{"Operation":"gt", "Field": "Size", "Value": "30"}</SimpleQuery>
</MetaQuery>请求头
此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。
请求元素
标量检索
名称 | 类型 | 是否必选 | 示例值 | 描述 |
mode | 字符串 | 是 | basic | 指定检索模式为标量检索。 |
MetaQuery | 容器 | 是 | 不涉及 | 查询条件的容器。 子节点:NextToken、MaxResults、Query、Sort、Order、Aggregations |
NextToken | 字符串 | 否 | MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw**** | 当Object总数大于设置的MaxResults时,用于翻页的token。 从NextToken开始按字典序返回Object信息列表。 第一次调用此接口时,设置此字段为空。 父节点:MetaQuery |
MaxResults | 整型 | 否 | 5 | 返回Object的最大个数,取值范围为0~100。 不设置此参数或者设置为0时,则默认值为100。 父节点:MetaQuery |
Query | 字符串 | 是 | {"Field": "Size","Value": "1048576","Operation": "gt"} | 查询条件。包括如下选项:
关于Query示例的更多信息,请参见DoMetaQuery。 父节点:MetaQuery |
Sort | 字符串 | 否 | Size | 对指定字段排序。关于支持排序的字段列表,请参见附录:标量检索的字段和操作符列表。 父节点:MetaQuery |
Order | 字符串 | 否 | asc | 排序方式。取值范围如下:
父节点:MetaQuery |
Aggregations | 容器 | 否 | 不涉及 | 聚合操作信息的容器。 子节点:Aggregation 父节点:MetaQuery |
Aggregation | 容器 | 否 | 不涉及 | 单个聚合操作信息的容器。 子节点:Field、Operation 父节点:Aggregations |
Field | 字符串 | 否 | Size | 字段名称。关于支持的字段以及字段对操作符的支持情况,请参见附录:标量检索的字段和操作符列表。 父节点:Aggregation |
Operation | 字符串 | 否 | sum | 聚合操作中的操作符。取值范围如下:
父节点:Aggregation |
向量检索
名称 | 类型 | 是否必选 | 示例值 | 描述 |
mode | 字符串 | 是 | semantic | 指定检索模式为向量检索。 |
MetaQuery | 容器 | 是 | 不涉及 | 查询条件的容器。 子节点:MaxResults、Query、MediaTypes、SimpleQuery |
MaxResults | 整型 | 否 | 5 | 返回Object的最大个数,取值范围为0~100。 不设置此参数或者设置为0时,则默认值为100。 父节点:MetaQuery |
Query | 字符串 | 是 | 俯瞰白雪覆盖的森林 | 输入检索内容。 父节点:MetaQuery |
MediaTypes | 容器 | 是 | 不涉及 | 多媒体元数据检索条件。 父节点:MetaQuery 子节点:MediaType |
MediaType | 字符串 | 是 | image | 选择检索的多媒体类型。取值如下:
父节点:MediaTypes |
SimpleQuery | 字符串 | 否 | {"Operation":"gt", "Field": "Size", "Value": "30"} | 查询条件。包括如下选项:
父节点:MetaQuery |
响应头
此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。
响应元素
标量检索
名称 | 类型 | 示例值 | 描述 |
MetaQuery | 容器 | 不涉及 | 查询结果的容器。 子节点:NextToken、Files、Aggregations |
NextToken | 字符串 | MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw**** | 当Object总数大于设置的MaxResults时,用于翻页的token。 下一次列出Object信息时以此值为NextToken,将未返回的结果返回。 当Object未全部返回时,此参数才有值。 父节点:MetaQuery |
Files | 容器 | 不涉及 | Object信息的容器。 子节点:File 父节点:MetaQuery |
File | 容器 | 不涉及 | 单个Object信息的容器。 子节点:Filename、Size、FileModifiedTime、OSSObjectType、OSSStorageClass、ObjectACL、ETag、OSSTaggingCount、OSSTagging、OSSCRC64 父节点:Files |
Filename | 字符串 | exampleobject.txt | Object完整路径。 父节点:File |
Size | 整型 | 120 | Object大小。单位为字节。 父节点:File |
FileModifiedTime | 字符串 | 2025-05-19T16:14:38+08:00 | Object的最近一次修改时间,遵循RFC3339Nano标准格式。 父节点:File |
FileCreateTime | 字符串 | 2021-07-29T15:04:05+07:00 | Object的创建时间,遵循RFC3339Nano标准格式 父节点:File |
OSSObjectType | 字符串 | Normal | Object的类型。取值范围如下:
父节点:File |
OSSStorageClass | 字符串 | Standard | Object的存储类型。取值范围如下:
父节点:File |
ObjectACL | 字符串 | default | Object的访问权限。取值范围如下:
父节点:File |
ETag | 字符串 | "fba9dede5f27731c9771645a3986****" | Object生成时会创建相应的ETag ,ETag用于标识一个Object的内容。
说明 ETag值可以用于检查Object内容是否发生变化。不建议使用ETag作为Object内容的MD5来校验数据完整性。 父节点:File |
OSSTaggingCount | 整型 | 2 | Object的标签个数。 父节点:File |
OSSTagging | 容器 | 不涉及 | 标签信息的容器。 子节点:Tagging 父节点:File |
Tagging | 容器 | 不涉及 | 单个标签信息的容器。 子节点:Key、Value 父节点:OSSTagging |
Key | 字符串 | owner | 标签或者用户自定义元数据的Key。 用户自定义元数据必须以 父节点:Tagging、UserMeta |
Value | 字符串 | John | 标签或者用户自定义元数据的Value。 父节点:Tagging、UserMeta |
OSSCRC64 | 字符串 | 4858A48BD1466884 | Object的64位CRC值。该64位CRC根据CRC-64/XZ标准计算得出。 父节点:File |
Aggregations | 容器 | 不涉及 | 聚合操作信息的容器。 子节点:Field、Operation、Operation、Value、Groups 父节点:MetaQuery |
Field | 字符串 | Size | 字段名称。 父节点:Aggregations |
Operation | 字符串 | sum | 聚合操作符。 父节点:Aggregations |
Value | 浮点数 | 200 | 聚合操作的结果值。 父节点:Aggregations |
Groups | 容器 | 不涉及 | 分组聚合的结果列表。 子节点:Value、Count 父节点:Aggregations |
Value | 字符串 | 100 | 分组聚合的值。 父节点:Groups |
Count | 整型 | 5 | 分组聚合的总个数。 父节点:Groups |
向量检索
名称 | 类型 | 示例值 | 描述 |
MetaQuery | 容器 | 不涉及 | 查询结果的容器。 子节点:Files |
Files | 容器 | 不涉及 | Object信息列表。 子节点:File 父节点:MetaQuery |
File | 容器 | 不涉及 | 单个Object信息。 父节点:Files 子节点:URI、Filename、Size、ObjectACL、FileModifiedTime、ETag、OSSCRC64、ProduceTime、ContentType、MediaType、LatLong、Title、OSSExpiration、AccessControlAllowOrigin、AccessControlRequestMethod、CacheControl、ContentDisposition、ContentEncoding、ContentLanguage、ImageHeight、ImageWidth、VideoWidth、VideoHeight、VideoStreams、AudioStreams、Subtitles、Bitrate、Artist、AlbumArtist、Composer、Performer、Album、Duration、Addresses、OSSObjectType、OSSStorageClass、OSSTaggingCount、OSSTagging |
URI | 字符串 | oss://examplebucket/test-object.jpg | Object完整路径。 父节点:File |
Filename | 字符串 | exampleobject.txt | Object名称。 父节点:File |
Size | 整型 | 120 | Object大小。单位为字节。 父节点:File |
ObjectACL | 字符串 | default | Object的访问权限。取值范围如下:
父节点:File |
FileModifiedTime | 字符串 | 2025-05-19T16:15:33+08:00 | Object的最近一次修改时间,遵循RFC3339Nano标准格式。 父节点:File |
ETag | 字符串 | "fba9dede5f27731c9771645a3986****" | Object生成时会创建相应的ETag ,ETag用于标识一个Object的内容。
说明 ETag值可以用于检查Object内容是否发生变化。不建议使用ETag作为Object内容的MD5来校验数据完整性。 父节点:File |
OSSCRC64 | 字符串 | 4858A48BD1466884 | Object的64位CRC值。该64位CRC根据CRC64/XZ标准计算得出。 父节点:File |
ProduceTime | 字符串 | 2021-06-29T14:50:13.011643661+08:00 | 设备记录的照片或视频的拍摄时间。 父节点:File |
ContentType | 字符串 | image/jpeg | MIME类型。 父节点:File |
MediaType | 字符串 | image | 多媒体类型。 父节点:File |
LatLong | 字符串 | 30.134390,120.074997 | 经纬度信息。 父节点:File |
Title | 字符串 | test | 文件标题。 父节点:File |
OSSExpiration | 字符串 | 2124-12-01T12:00:00.000Z | 文件过期时间。 父节点:File |
AccessControlAllowOrigin | 字符串 | 允许的跨域请求的来源。 父节点:File | |
AccessControlRequestMethod | 字符串 | PUT | 跨域请求中用到的方法。 父节点:File |
CacheControl | 字符串 | no-cache | Object被下载时网页的缓存行为。 父节点:File |
ContentDisposition | 字符串 | attachment; filename =test.jpg | Object被下载时的名称。 父节点:File |
ContentEncoding | 字符串 | UTF-8 | Object被下载时的内容编码格式。 父节点:File |
ContentLanguage | 字符串 | zh-CN | Object内容使用的语言。 父节点:File |
ImageHeight | 整型 | 500 | 图片高度,单位为像素(px)。 父节点:File |
ImageWidth | 整型 | 270 | 图片宽度,单位为像素(px)。 父节点:File |
VideoWidth | 整型 | 1080 | 视频画面宽度,单位为像素(px)。 父节点:File |
VideoHeight | 整型 | 1920 | 视频画面高度,单位为像素(px)。 父节点:File |
VideoStreams | 容器 | 不涉及 | 视频流列表。 父节点:File 子节点:VideoStream |
VideoStream | 容器 | 不涉及 | 视频流。 父节点:VideoStreams 子节点:CodecName、Language、Bitrate、FrameRate、StartTime、Duration、FrameCount、BitDepth、PixelFormat、ColorSpace、Height、Width |
CodecName | 字符串 | h264 | 编码器名称。 父节点:VideoStream |
Language | 字符串 | en | 视频流中使用的语言,格式为BCP 47。 父节点:VideoStream |
Bitrate | 整型 | 5407765 | 码率,单位为比特每秒(bit/s)。 父节点:VideoStream |
FrameRate | 字符串 | 25/1 | 视频流帧率。 父节点:VideoStream |
StartTime | 双精度浮点数 | 0.000000 | 视频流起始时间,单位为秒(s)。 父节点:VideoStream |
Duration | 双精度浮点数 | 22.88 | 视频流持续时长,单位为秒(s)。 父节点:VideoStream |
FrameCount | 整型 | 572 | 视频帧数。 父节点:VideoStream |
BitDepth | 整型 | 8 | 像素位宽。 父节点:VideoStream |
PixelFormat | 字符串 | yuv420p | 视频流像素格式。 父节点:VideoStream |
ColorSpace | 字符串 | bt709 | 色彩空间。 父节点:VideoStream |
Height | 整型 | 720 | 视频流画面高度,单位为像素(px)。 父节点:VideoStream |
Width | 整型 | 1280 | 视频流画面宽度,单位为像素(px)。 父节点:VideoStream |
AudioStreams | 容器 | 不涉及 | 音频流列表。 父节点:File 子节点:AudioStream |
AudioStream | 容器 | 不涉及 | 音频流。 父节点:AudioStreams 子节点:CodecName、Bitrate、SampleRate、StartTime、Duration、Channels、Language |
CodecName | 字符串 | aac | 编码器名称。 父节点:AudioStream |
Bitrate | 整型 | 320087 | 码率,单位为比特每秒(bit/s)。 父节点:AudioStream |
SampleRate | 整型 | 48000 | 采样率,单位为赫兹(Hz)。 父节点:AudioStream |
StartTime | 双精度浮点数 | 0.0235 | 音频流起始时间,单位为秒(s)。 父节点:AudioStream |
Duration | 双精度浮点数 | 3.690667 | 音频流持续时长,单位为秒(s)。 父节点:AudioStream |
Channels | 整型 | 2 | 声道数量。 父节点:AudioStream |
Language | 字符串 | en | 音频流中使用的语言,格式为BCP 47。 父节点:AudioStream |
Subtitles | 容器 | 不涉及 | 字幕流列表。 父节点:File 子节点:Subtitle |
Subtitle | 容器 | 不涉及 | 字幕流。 父节点:Subtitles 子节点:CodecName、Language、StartTime、Duration |
CodecName | 字符串 | mov_text | 编码器名称。 父节点:Subtitle |
Language | 字符串 | en | 字幕语言,格式为BCP 47。 父节点:Subtitle |
StartTime | 双精度浮点数 | 0.000000 | 字幕流起始时间,单位为秒(s)。 父节点:Subtitle |
Duration | 双精度浮点数 | 71.378 | 字幕流持续时长,单位为秒(s)。 父节点:Subtitle |
Bitrate | 整型 | 13091201 | 码率,单位为比特每秒(bit/s)。 父节点:File |
Artist | 字符串 | Jane | 艺术家。 父节点:File |
AlbumArtist | 字符串 | Jenny | 演唱者。 父节点:File |
Composer | 字符串 | Jane | 作曲家。 父节点:File |
Performer | 字符串 | Jane | 演奏者。 父节点:File |
Album | 字符串 | FirstAlbum | 专辑。 父节点:File |
Duration | 双精度浮点数 | 15.263000 | 视频的总时长。单位秒。 父节点:File |
Addresses | 容器 | 不涉及 | 地址信息。 父节点:File 子节点:Address |
Address | 容器 | 不涉及 | 地址信息。 父节点:Addresses 子节点:AddressLine、City、District、Language、Province、Township |
AddressLine | 字符串 | 中国浙江省杭州市余杭区文一西路969号 | 完整地址。 父节点:Address |
City | 字符串 | 杭州市 | 城市 父节点:Address |
District | 字符串 | 余杭区 | 区 父节点:Address |
Language | 字符串 | zh-Hans | 语言,格式为BCP 47。 父节点:Address |
Province | 字符串 | 浙江省 | 省份 父节点:Address |
Township | 字符串 | 文一西路 | 街道 父节点:Address |
OSSObjectType | 字符串 | Normal | Object的类型。 父节点:File |
OSSStorageClass | 字符串 | Standard | Object的存储类型。 父节点:File |
OSSTaggingCount | 整型 | 2 | Object的标签个数。 父节点:File |
OSSTagging | 容器 | 不涉及 | 标签信息列表。 子节点:Tagging 父节点:File |
Tagging | 容器 | 不涉及 | 单个标签信息的容器。 子节点:Key、Value 父节点:OSSTagging |
Key | 字符串 | owner | 标签的Key。 父节点:Tagging |
Value | 字符串 | John | 标签的Value。 父节点:Tagging |
Key | 字符串 | owner | 用户自定义元数据的Key。 父节点:Tagging |
Value | 字符串 | John | 用户自定义元数据的Value。 父节点:Tagging |
Insights | 容器 | 不涉及 | 文件的描述信息。 子节点:Video、Image |
Video | 容器 | 不涉及 | 视频文件的描述信息。 父节点:Insights 子节点:Caption、Description |
Caption | 字符串 | 不涉及 | 简短描述信息。 父节点:Video |
Image | 容器 | 不涉及 | 图片文件的描述信息 父节点:Insights 子节点:Caption、Description |
Caption | 字符串 | 不涉及 | 简短描述信息。 父节点:Image |
Description | 字符串 | 不涉及 | 详细描述信息。 父节点:Image |
示例
请求示例
标量检索,按 Size 降序返回前 10 条大于 1 MB 的文件:
POST /?metaQuery&action=doMetaQuery&mode=basic 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 Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <MetaQuery> <Query>{"Field":"Size","Operation":"gt","Value":"1048576"}</Query> <Sort>Size</Sort> <Order>desc</Order> <MaxResults>10</MaxResults> </MetaQuery>标量检索,按 ContentType 分组并统计总字节数:
POST /?metaQuery&action=doMetaQuery&mode=basic 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 Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <MetaQuery> <Query>{"Field":"Size","Operation":"gt","Value":"0"}</Query> <MaxResults>0</MaxResults> <Aggregations> <Aggregation> <Field>Size</Field> <Operation>sum</Operation> </Aggregation> <Aggregation> <Field>ContentType</Field> <Operation>group</Operation> </Aggregation> </Aggregations> </MetaQuery>向量检索,以"客厅里的猫"做图片语义检索:
POST /?metaQuery&action=doMetaQuery&mode=semantic 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 Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <MetaQuery> <Query>客厅里的猫</Query> <MediaTypes> <MediaType>image</MediaType> </MediaTypes> <SimpleQuery>{"Field":"Size","Operation":"gt","Value":"102400"}</SimpleQuery> <MaxResults>20</MaxResults> </MetaQuery>
返回示例
标量检索:
HTTP/1.1 200 OK x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F6 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>123</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> </File> </Files> <Aggregations> <Aggregation> <Field>Size</Field> <Operation>sum</Operation> <Value>12345678</Value> </Aggregation> <Aggregation> <Field>ContentType</Field> <Operation>group</Operation> <Groups> <Group> <Value>image/jpeg</Value> <Count>256</Count> </Group> <Group> <Value>video/mp4</Value> <Count>48</Count> </Group> </Groups> </Aggregation> </Aggregations> </MetaQuery>向量检索:
HTTP/1.1 200 OK x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F7 Date: Wed, 20 May 2026 09:00:01 GMT Content-Type: application/xml Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <MetaQuery> <Files> <File> <Filename>photos/cat-in-living-room.jpg</Filename> <Size>1572864</Size> <FileModifiedTime>2026-05-18T10:00:00.000+08:00</FileModifiedTime> <ContentType>image/jpeg</ContentType> <MediaType>image</MediaType> <ImageWidth>4032</ImageWidth> <ImageHeight>3024</ImageHeight> <Insights> <Image> <Caption>一只橘猫趴在客厅沙发上,阳光从窗外洒入。</Caption> </Image> </Insights> <Labels> <Label> <LabelName>猫</LabelName> <LabelConfidence>0.98</LabelConfidence> </Label> <Label> <LabelName>客厅</LabelName> <LabelConfidence>0.92</LabelConfidence> </Label> </Labels> </File> </Files> </MetaQuery>