Call the GetVectors API to retrieve specific vector data by key.
Permissions
Alibaba Cloud accounts have all permissions by default. However, RAM users and RAM roles have no permissions by default. The Alibaba Cloud account or an administrator must grant permissions for this operation using a RAM Policy or a Bucket Policy.
API | Action | Description |
GetVectors |
| Retrieve vector data. |
Request Syntax
POST /?getVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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 Header Definitions.
Request Parameters
Name | Data Type | Required | Example Value | Description |
indexName | string | Yes | vectorindex1 | The index name. |
keys | string array | Yes | ["doc-001", "doc-002"] | The primary keys of the vectors to query. Duplicate primary keys are allowed. Limits:
|
returnData | Boolean value | No | false | Return vector data. Values:
|
returnMetadata | Boolean value | No | false | Return metadata. Values:
|
Response headers
This operation returns only common response headers. For more information, see Common HTTP Headers.
Response Elements
Name | Data Type | Example Value | Description |
vectors | object array | - | The list of returned vectors. If a queried primary key does not exist, no error is reported, but the result for that key is not returned. |
key | string | doc-001 | The vector primary key. When querying by primary key, if a vector corresponding to a key in the request does not exist, the request does not report an error. The returned result only includes existing vectors and does not include data for that key. Parent node: vectors |
data | object | - | Vector data (returned only when returnData is true). Parent node: vectors |
metadata | object | - | Metadata (returned only when returnMetadata is true). Parent node: vectors |
Examples
Example request
POST /?getVectors 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
{
"indexName": "vectorindex1",
"keys": ["doc-001", "doc-002"],
"returnData": true,
"returnMetadata": true
}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": [
{
"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:
Command Line Tool ossutil
For more information about the ossutil command for the GetVectors operation, see get-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 in the request body is invalid. |
AccessDenied | 403 | Possible reasons for this error are:
|
NoSuchVectorIndex | 404 | The specified vector index does not exist. |
QpsLimitExceeded | 503 | QPS limit exceeded (request rate limited). |