Call the GetVectors operation to retrieve vector data for specified keys.
Permissions
An Alibaba Cloud account has all permissions by default. However, Resource Access Management (RAM) users and RAM roles have no permissions by default. The Alibaba Cloud account or an administrator must grant permissions using a RAM policy or a bucket policy.
API | Action | Description |
GetVectors |
| Gets 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 request 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:
|
returnData | Boolean | No | false | Specifies whether to return vector data. Valid values:
|
returnMetadata | Boolean | No | false | Specifies whether to return metadata. Valid values:
|
Response headers
This operation uses only common response headers. For more information, see Common response headers.
Response elements
Name | Data type | Example | Description |
vectors | Array of objects | - | A list of vectors. If a primary key that you query does not exist, no error is reported and the result for that key is not returned. |
key | String | doc-001 | The primary key of the vector. If a vector for a specified key does not exist, the request does not fail. The response includes only data for existing vectors and omits the entry for the non-existent key. Parent node: vectors |
data | Object | - | The vector data. This element is returned only when `returnData` is set to `true`. Parent node: vectors |
metadata | Object | - | The metadata. This element is 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.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"
}
}
]
}Error codes
Error code | HTTP status code | Description |
VectorIndexParameterInvalid | 400 | The vector index parameter in the request is invalid. |
MalformedJson | 400 | The JSON format of the request body is invalid. |
AccessDenied | 403 | Possible causes for this error:
|
NoSuchVectorIndex | 404 | The specified vector index does not exist. |
QpsLimitExceeded | 503 | The request rate is throttled because the number of queries per second (QPS) exceeds the limit. |