GetVectorIndex

Permissions

Alibaba Cloud accounts have full permissions by default. RAM users and RAM roles require explicit authorization through a RAM policy or a bucket policy.

API	Action	Description
GetVectorIndex	`oss:GetVectorIndex`	Retrieves vector index information.

Request syntax

POST /?getVectorIndex HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
{
   "indexName": "string"
}

Request headers

This operation uses only common request headers.

Request parameters

Name	Data type	Required	Example	Description
indexName	string	Yes	vectorindex1	Index name.

Response headers

This operation uses only common response headers.

Response elements

Name	Data type	Example	Description
index	container	-	Container for vector index information.
bucketArn	string	acs:ossvector:cn-hangzhou:174****:my-vector-bucket	The resource name (ARN) of the vector bucket that the index belongs to, in the format acs:ossvector:{region}:{accountId}:{bucketName}. Parent node: index
indexName	string	vectorindex1	Index name. Parent node: index
createTime	string	2025-04-17T10:56:21.000Z	Index creation time in GMT. Parent node: index
dataType	string	float32	Vector data type. Parent node: index
dimension	Integer	1024	Number of vector dimensions. Parent node: index
distanceMetric	string	euclidean	Distance metric function. Parent node: index
metadata	container	-	Metadata configuration. Parent node: index
nonFilterableMetadataKeys	string array	["category", "timestamp"]	Non-filterable metadata fields. Parent node: metadata
status	string	enable	Index status. Valid values: creating enable deleting
mode	string	fusion	The index mode. Valid values: standard (Standard mode) fusion (Fusion mode) Parent node: index

Note

The preceding response elements are returned for Standard-mode indexes. For Fusion-mode indexes, in addition to basic attributes such as index, bucketArn, indexName, createTime, mode, and status, the response also returns the complete schema configuration (schemaConfiguration) that was defined when the index was created, and does not return Standard-mode fields such as dataType, dimension, and distanceMetric. Standard-mode and Fusion-mode indexes can coexist in the same vector bucket.

Examples

Standard Mode

Request example

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

{
   "indexName": "vectorindex1"
}

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
Content-type: application/json

{
   "index": { 
      "bucketArn": "acs:ossvector:cn-hangzhou:174****:my-vector-bucket",
      "createTime": "2025-04-17T10:56:21.000Z",
      "indexName": "vectorindex1",
      "mode": "standard",
      "dataType": "float32",
      "dimension": 1024,
      "distanceMetric": "euclidean",
      "metadata": { 
         "nonFilterableMetadataKeys": ["category", "timestamp"]
      },
      "status": "enable"
   }
}

Fusion Mode

Request example

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

{
   "indexName": "vectorindex1"
}

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
Content-type: application/json

{
   "index": {
      "bucketArn": "acs:ossvector:cn-hangzhou:174****:my-vector-bucket",
      "createTime": "2025-04-17T10:56:21.000Z",
      "indexName": "vectorindex1",
      "mode": "fusion",
      "schemaConfiguration": {
         "fields": [
            {
               "name": "vector_1",
               "type": "vector",
               "dataType": "float32",
               "dimension": 1024,
               "distanceMetric": "euclidean"
            },
            {
               "name": "price",
               "type": "double"
            },
            {
               "name": "tag",
               "type": "string"
            },
            {
               "name": "user_id",
               "type": "string",
               "isPartitionKey": true
            }
         ]
      },
      "status": "enable"
   }
}

SDK

Available SDKs for GetVectorIndex:

ossutil command-line interface

Run GetVectorIndex from the command line with ossutil get-vector-index.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	Invalid vector index parameter in the request.
MalformedJson	400	Invalid JSON in the request body.
AccessDenied	403	Possible causes: Authentication information is missing from the request. Insufficient permissions.
NoSuchVectorIndex	404	The vector index does not exist.