DocsICP FilingConsole
官方文档
首页

SemanticQuery

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

Call the SemanticQuery operation to perform a semantic search within a specified dataset. This operation provides functionality equivalent to the vector search feature of DoMetaQuery but requires you to explicitly specify the datasetName in the request. This allows you to precisely query a specific dataset when a bucket contains multiple datasets. Parameters for search by image are reserved and not currently supported.

Usage notes

  • A RAM user must have the oss:MetaQuery permission to call this operation.

  • You must enable vector search by using the OpenMetaQuery operation before you can use this operation.

  • The dataset you want to query must have content awareness configured for the corresponding media type. For new integrations, configure content awareness details by using the datasetConfig parameter of the CreateDataset or UpdateDataset operation.

  • All parameters for this operation must be passed in the URL query string. The HTTP body is not accepted.

  • This operation returns semantic search results in descending order of relevance. This operation does not support pagination (the response does not include a NextToken) or aggregation.

  • This operation queries only a single dataset specified by datasetName. Cross-dataset search is not currently supported. To query multiple datasets, call this operation separately for each one.

  • Currently, you can only search by passing natural language text in the query parameter. The sourceURI parameter is reserved for search by image and is not yet supported.

Request syntax

POST /?metaQuery&action=semanticQuery&datasetName=DatasetName&query=Query&mediaTypes=MediaTypes&simpleQuery=SimpleQuery&withFields=WithFields&maxResults=MaxResults 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 parameters

Parameter

Type

Required

Example

Description

datasetName

String

Yes

photos-2026

The name of the dataset to query.

query

String

Yes

sunset by the sea

The natural language search query. The query must be URL-encoded. The query length must be between 1 and 1,024 characters.

sourceURI

String

No

N/A

A reserved parameter for search by image. The format is oss://{bucket}/{object-key}. This parameter is not currently supported. Use the query parameter to perform a natural language search.

mediaTypes

Array of strings

No

["image"]

The target media types. When passed in the URL query string, this parameter must be JSON-serialized and URL-encoded.

Child node: MediaType

MediaType

String

No

image

The target media type. Valid values:

  • image

  • video

  • audio

  • document

Parent node: mediaTypes

simpleQuery

Query object

No

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

An additional structured filter to further refine the semantic search results. When passed in the URL query string, this parameter must be JSON-serialized and URL-encoded. For a list of supported filter fields and operators, see Appendix: Fields and operators for vector search.

Child nodes: Field, Operation, Value, SubQueries

Field

String

No

Size

The name of the field. Common fields include Size, Filename, FileModifiedTime, ObjectACL, OSSStorageClass, OSSTagging.<key>, OSSUserMeta.<key>, and Labels.LabelName.

Parent node: simpleQuery

Operation

String

Yes

gt

The operator. Valid values: eq, gt, gte, lt, lte, match, prefix, and, or, not.

Parent node: simpleQuery

Value

String

No

102400

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

Parent node: simpleQuery

SubQueries

Array of Query objects

No

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

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

Each element in the array is a Query object, which has the same structure as simpleQuery and allows for recursive nesting.

Parent node: simpleQuery

withFields

Array of strings

No

["URI","Insights"]

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

Child node: WithField

WithField

String

No

Insights

The name of a single projection field, such as URI, Size, FileModifiedTime, or Insights.

Parent node: withFields

maxResults

Integer

No

100

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

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 search results.

Child node: Files

Files

container

No

N/A

Contains the list of matched files, sorted in descending order of relevance.

Child node: File

Parent node: MetaQuery

File

container

No

N/A

The metadata of a single file. For a complete list of fields, see File data structure.

Parent node: Files

Examples

Request examples

Search for images in the photos-2026 dataset with the natural language query "sunset by the sea":

POST /?metaQuery&action=semanticQuery&datasetName=photos-2026&query=sunset%20by%20the%20sea&mediaTypes=%5B%22image%22%5D&maxResults=20 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 URL-decoded parameters are: query=sunset by the sea and mediaTypes=["image"].

Perform a semantic search for "snowy scenery" within images that are larger than 100 KB:

POST /?metaQuery&action=semanticQuery&datasetName=photos-2026&query=snowy%20scenery&mediaTypes=%5B%22image%22%5D&simpleQuery=%7B%22Field%22%3A%22Size%22%2C%22Operation%22%3A%22gt%22%2C%22Value%22%3A%22102400%22%7D&maxResults=20 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 URL-decoded parameters are:

  • query=snowy scenery

  • mediaTypes=["image"]

  • simpleQuery={"Field":"Size","Operation":"gt","Value":"102400"}

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F9
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/snow-mountain.jpg</Filename>
      <Size>3145728</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>A snow-covered mountain range with sunlight breaking through the clouds.</Caption>
        </Image>
      </Insights>
      <Labels>
        <Label>
          <LabelName>Snowy Mountain</LabelName>
          <LabelConfidence>0.99</LabelConfidence>
        </Label>
      </Labels>
    </File>
  </Files>
</MetaQuery>
Previous：SimpleQueryNext：CreateDataset