QueryVectors - Object Storage Service - Alibaba Cloud Documentation Center

You can call the QueryVectors operation to perform a vector similarity search.

Permissions

An Alibaba Cloud account has all permissions by default. However, Resource Access Management (RAM) users and RAM roles do not have any permissions by default. The Alibaba Cloud account or an administrator must grant permissions to them using a RAM policy or a bucket policy.

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

Request syntax

The recall rate for QueryVectors is low for 30 seconds after a vector index is created. After data is written using PutVectors, it becomes available for queries using 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

Name	Data type	Required	Example	Description
indexName	String	Yes	vectorindex1	The name of the index.
queryVector	Container	Yes	N/A	The query vector. The dimension must be the same as the dimension of the vector index.
filter	Container	No	N/A	Filters query data based on metadata. When you configure filterable metadata: The total length of filterable metadata in a single filter instruction cannot exceed 64 KB. The number of filterable metadata items in a single filter instruction cannot exceed 1,024. The 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	Number	Yes	10	Specifies the number of most similar results to return. The default range is 1 to 30. You can contact technical support to request to increase the TopK upper limit to 100.

Filter operators

Operator	Supported type	Description
`$eq`	String	Performs an exact match for a single value. When compared with metadata of the array type, this operator returns true if the input value matches any element in the array.
`$ne`	String	Not equal to
`$in`	String array	Matches any value in an array. This is similar to the `IN` operation in SQL.
`$nin`	String array	Does not match any value in an array. This is 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 multiple conditions.
`$or`	Non-empty array of filters	Performs a logical OR operation on multiple conditions.

Response headers

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

Response elements

Name	Data type	Example	Description
vectors	Array of objects	/	The list of returned vectors. If the queried primary key does not exist, no error is reported and the result for the key is not returned.
key	String	doc-001	The primary key of the vector. Parent node: vectors
distance	float32	0.25	The similarity distance between the 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	/	All metadata. 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"
         }
      }
   ]
}

SDK

The QueryVectors operation is available in the following software development kits (SDKs):

Retrieve vectors (Python SDK V2)
Retrieve vectors (Go SDK V2)

ossutil command line interface

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 JSON format of the request body is invalid.
AccessDenied	403	The error may be returned for the following reasons: User authentication information is not included in the request. 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.