Use QueryVectors for vector similarity search - Object Storage Service

Call QueryVectors to perform a vector similarity search.

Permissions

By default, an Alibaba Cloud account has full permissions, while its RAM users and RAM roles have none. To grant permissions, the Alibaba Cloud account owner or an administrator must use a RAM policy or a bucket policy.

API	Action	Description
QueryVectors	`oss:QueryVectors`	Queries vector data.

Request syntax

For the first 30 seconds after a vector index is created, the recall rate for QueryVectors is low. After you write data by using PutVectors, the data becomes queryable with QueryVectors in approximately 2 to 3 seconds.

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "string",
   "queryVector": {
       "float32":[float]
    },
   "returnDistance": boolean,
   "returnMetadata": boolean,
   "topK": int
}

Request headers

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

Request parameters

Parameter	Type	Required	Example	Description
indexName	String	Yes	vectorindex1	The name of the vector index.
queryVector	Container	Yes	N/A	The query vector. The dimension of the vector must match the dimension of the vector index.
filter	Container	No	N/A	Filters search results based on metadata. The following limits apply: The total size of metadata in a single filter expression cannot exceed 64 KB. The number of metadata fields in a single filter expression cannot exceed 1,024. A `filter condition` can be nested up to 8 levels deep.
returnDistance	Boolean	No	false	Specifies whether to return the similarity distance. Valid values: true false (default)
returnMetadata	Boolean	No	false	Specifies whether to return metadata. Valid values: true false (default)
topK	Integer	Yes	10	The number of most similar results to return. The value must be between 1 and 100.

Filter operators

Operator	Type	Description
`$eq`	String	Matches a single value. If the metadata field is an array, the operator matches any element in that array.
`$ne`	String	Not equal to.
`$in`	String array	Matches any value in the array (similar to the SQL `IN` operation)
`$nin`	String array	Does not match any of the values in the array (similar to the `NOT IN` operation in SQL)
`$exists`	Boolean	Checks whether a metadata key exists.
`$and`	Non-empty array of filters	Performs a logical AND operation on an array of two or more filter expressions.
`$or`	Non-empty array of filters	Performs a logical OR operation on an array of two or more filter expressions.

Response headers

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

Response elements

Parameter	Type	Example	Description
vectors	Array of objects	/	An array of the returned vector objects. If a specified vector primary key does not exist, it is omitted from the response and no error is reported.
key	String	doc-001	The vector primary key. Parent node: vectors
distance	Float	0.25	The similarity distance between the result vector and the query vector. A smaller value indicates a higher similarity. This parameter is returned only when `returnDistance` is set to `true`. Parent node: vectors
metadata	Object	/	The complete metadata for the vector. This parameter is returned only when `returnMetadata` is set to `true`. Parent node: vectors

Examples

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}

Example response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      },
      { 
         "distance": 0.25,
         "key": "doc-003",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations",
             "year": "2020"
         }
      }
   ]
}

SDKs

The QueryVectors operation is available in the following SDKs:

Ossutil CLI

The ossutil command for the QueryVectors operation is query-vectors.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameter provided in the request is invalid.
MalformedJson	400	The request body is not in a valid JSON format.
AccessDenied	403	This error occurs for one of the following reasons: The request does not include authentication information. You do not have the required permissions for the operation.
NoSuchVectorIndex	404	The specified vector index does not exist.
QpsLimitExceeded	503	The number of queries per second (QPS) exceeds the limit. The request rate is throttled.