PutVectorIndex - Object Storage Service - Alibaba Cloud Documentation Center

The PutVectorIndex API creates a vector index in a vector bucket.

Notes

A single vector bucket can contain a maximum of 100 vector indexes. To increase this quota, contact Technical Support.
A maximum of 5 PutVectorIndex requests are supported per second.

Permissions

By default, Alibaba Cloud accounts have all permissions, whereas Resource Access Management (RAM) users and RAM roles have no permissions. The Alibaba Cloud account or an administrator must grant permissions through a RAM policy or a bucket policy.

API	Action	Description
PutVectorIndex	`oss:PutVectorIndex`	Creates a vector index.

Request syntax

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

{
   "dataType": "string",
   "dimension": int,
   "distanceMetric": "string",
   "indexName": "string",
   "metadata": { 
      "nonFilterableMetadataKeys": [string, string]
   }
}

Request headers

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

Request parameters

Name	Data type	Required	Example	Description
dataType	String	Yes	float32	The data type of the vector data. This parameter is not configurable by users. Default value: float32.
dimension	Value	Yes	512	The vector dimensions. Valid values: 1 to 4096. Default value: 512.
distanceMetric	String	Yes	euclidean	The distance measure function. Valid values: euclidean: Euclidean distance (default) cosine: Cosine distance
indexName	String	Yes	vectorindex1	The custom name of the index. The name must be globally unique within the vector bucket and be 1 to 63 characters in length. The name can contain only letters and digits, and must start with a letter.
metadata	Object	No	-	The container for metadata configurations. Only non-filterable metadata is supported.
nonFilterableMetadataKeys	Array of strings	No	["field1", "field2"]	The configuration for non-filterable metadata. The following limits apply: The number of metadata entries must be between 1 and 10. The name of each metadata primary key must be 1 to 63 bytes in length. The name can contain uppercase letters, lowercase letters, digits, and underscores (_). It must start with an uppercase letter, a lowercase letter, or an underscore (_). Parent node: metadata

Response headers

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

Examples

Sample request

POST /?putVectorIndex 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

{
   "dataType": "float32",
   "dimension": 1024,
   "distanceMetric": "euclidean",
   "indexName": "vectorindex1",
   "metadata": { 
      "nonFilterableMetadataKeys": ["category", "timestamp"]
   }
}

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

SDK

The PutVectorIndex API is supported by the following software development kits (SDKs):

Create a vector index (Python SDK V2)
Create a vector index (Go SDK V2)

ossutil command-line tool

For the ossutil command that corresponds to the PutVectorIndex API, see put-vector-bucket.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameters provided in the request are invalid.
MalformedJson	400	The JSON format in the request body is invalid.
VectorBucketIndexExceedLimit	400	The number of created indexes has reached the upper limit. A maximum of 100 vector indexes can be created in a single vector bucket.
AccessDenied	403	This error is returned for the following possible reasons: User authentication information is not included in the request. You do not have the required permissions.
VectorBucketIndexAlreadyExist	409	The specified index name already exists. You cannot create an index with the same name.