PutVectorIndex - Criar índice vetorial no bucket de vetores do OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

Usage notes

A single vector bucket can contain a maximum of 100 vector indexes. To increase this quota, contact technical support.
The PutVectorIndex operation supports a maximum of five requests per second.

Permissions

An Alibaba Cloud account has all permissions by default. RAM users and roles have no permissions by default and must be granted access 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-internal.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.

Request parameters

Name	Data type	Required	Example	Description
dataType	String	Yes	float32	Data type of vector data. Not user-configurable. Default: float32.
dimension	Value	Yes	512	The vector dimensions. Valid values: 1 to 4096. Default value: 512.
distanceMetric	String	Yes	euclidean	Distance measure function. Valid values: euclidean: Euclidean distance (default) cosine: Cosine distance
indexName	String	Yes	vectorindex1	Custom index name. Must be unique within the vector bucket. Length: 1 to 63 characters. The name can contain only letters and digits and must start with a letter.
metadata	Object	No	-	Metadata configurations. Only non-filterable metadata is supported.
nonFilterableMetadataKeys	Array of strings	No	["field1", "field2"]	Non-filterable metadata fields. Limits: 1 to 10 fields. Each key name must be 1 to 63 bytes. Allowed characters: letters, digits, and underscores (_). Must start with a letter or underscore. Parent node: metadata

Response headers

This operation uses only common response headers.

Examples

Sample request

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

{
   "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

SDKs that support PutVectorIndex:

ossutil command line interface

The corresponding ossutil command is put-vector-index.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	Invalid vector index parameters.
MalformedJson	400	The JSON format of the request body is invalid.
VectorBucketIndexExceedLimit	400	The vector bucket has reached the maximum of 100 vector indexes.
AccessDenied	403	Possible causes: User authentication information is not included in the request. You do not have the required permissions for the operation.
VectorBucketIndexAlreadyExist	409	An index with the specified name already exists.