GetVectors - Object Storage Service - Alibaba Cloud Documentation Center

Permissions

Alibaba Cloud accounts have all permissions by default. RAM users or RAM roles do not have any permissions by default. An Alibaba Cloud account or an administrator must grant permissions by using a RAM policy or a bucket policy.

API	Action	Description
GetVectors	`oss:GetVectors`	Gets vector data.

Request syntax

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

{
   "indexName": "string",
   "keys": [string, string, string],
   "returnData": boolean,
   "returnMetadata": boolean
}

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.
keys	Array of strings	Yes	["doc-001", "doc-002"]	The primary keys of the vectors to query. Duplicate primary keys are allowed. Constraints: Number of keys: 1 to 100. Length of a key: 1 to 1024.
returnData	Boolean	No	false	Specifies whether to return vector data. Valid values: true false (default)
returnMetadata	Boolean	No	false	Specifies whether to return metadata. Valid values: true false (default)

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 returned vectors. If a queried primary key does not exist, no error is reported and the result for that key is omitted.
key	String	doc-001	The primary key of the vector. If a requested key does not match an existing vector, no error is reported and the response omits that key. Parent node: vectors
data	Object	-	The vector data. Returned only when returnData is set to true. Parent node: vectors
metadata	Object	-	The metadata. Returned only when returnMetadata is set to true. Parent node: vectors

Examples

Sample request

POST /?getVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.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

{
   "indexName": "vectorindex1",
   "keys": ["doc-001", "doc-002"],
   "returnData": true,
   "returnMetadata": true
}

Sample 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": [ 
      { 
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "float32": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

SDK

The following SDKs support the GetVectors operation:

ossutil command-line interface

For the ossutil command that corresponds to the GetVectors operation, see get-vectors.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameter is invalid.
MalformedJson	400	The JSON in the request body is malformed.
AccessDenied	403	Possible causes for this error: The request does not include user authentication information. You do not have the required permissions for the operation.
NoSuchVectorIndex	404	The specified vector index does not exist.
QpsLimitExceeded	503	The request was throttled because the QPS limit was exceeded.