Use PutVectors to write vector data to a vector index - Object Storage Service

Usage notes

A single vector index can store up to 2 billion vectors.
A single PutVectors request can write up to 500 vectors, and supports a maximum of 5 requests per second (QPS).

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 owner or an administrator must grant operation permissions using a RAM policy or a bucket policy.

API	Action	Description
PutVectors	`oss:PutVectors`	Writes vector data.

Request syntax

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

{
   "indexName": "string",
   "vectors": [ 
      { 
         "data": {
            "float32":[float]
         },
         "key": "string",
         "metadata": {
             "key1": ["value1", "value2"],
             "key2": "value2"
         }
      }
   ]
}

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.
vectors	Container	Yes	-	The array of vectors to write. The number of elements in the container must be between 1 and 500.
key	String	Yes	doc-001	The primary key that uniquely identifies the vector. Constraints: If a key already exists, the vector is overwritten. If duplicate keys exist in the same batch, an error is returned for all entries. The key must be 1 to 1,024 characters in length. The key must be in UTF-8 format. Parent node: vectors
data	Container	Yes	-	The content of the vector. Constraints: The number of vector dimensions must match the number of dimensions configured for the vector index. For the cosine distance measure, zero vectors (vectors where all elements are zero) are not allowed. The vector data must contain only valid floating-point numbers. Invalid values, such as NaN (Not a Number) or Infinity, are not allowed. Parent node: vectors
float32	Array of numbers	Yes	[0.1, 0.2, 0.3]	The vector data of the float32 type. The number of vector dimensions must match the number of dimensions defined for the index. Zero vectors are not allowed when you use the cosine distance measure. Parent node: data
metadata	Container	No	-	The metadata. Constraints: Total size: ≤ 40 KB Constraints for filterable metadata: Length: 0 to 10 Size of the filterable part: ≤ 2 KB Supported types: string or string array. Parent node: vectors

Response headers

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

Examples

Request example

POST /?putVectors 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",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      {
         "key": "doc-002",
         "data": {
            "float32": [0.6, 0.7, 0.8, 0.9, 1.0]
         },
         "metadata": {
             "category": ["technology", "database"],
             "title": "Advanced Database Indexing"
         }
      }
   ]
}

Response example

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

SDK

The following SDKs support the PutVectors operation:

ossutil command-line interface

For information about the ossutil command for the PutVectors operation, see put-vectors.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameters provided in the request are invalid, or a single vector index table stores more than 50 million rows of vector data.
MalformedJson	400	The JSON format in the request body is invalid.
AccessDenied	403	Possible causes for this error: 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. If the HTTP status code is 5xx, only some of the data in the same batch may be successfully written. The write operation does not ensure atomicity.