Use the ListVectors operation to list vector data from a vector index - Object Storage Service - Alibaba Cloud - Object Storage Service

The ListVectors operation lists all vector data in a vector index.

Permissions

By default, an Alibaba Cloud account has full permissions to access all resources. RAM users and RAM roles do not have any permissions by default. The Alibaba Cloud account owner or an administrator must grant them permissions by using a RAM policy or a bucket policy.

API	Action	Description
ListVectors	`oss:ListVectors`	Lists vector data.

Request syntax

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

{
   "indexName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int,
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    }
}

Request headers

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

Request parameters

Parameter	Type	Required	Example	Description
indexName	String	Yes	vectorindex1	The name of the vector index.
maxResults	Integer	No	500	The maximum number of results to return per request. Default value: 500. Maximum value: 1,000.
nextToken	String	No	CAESCG15aC-xxxxx	The query token. Set this parameter to the value of `nextToken` from the previous response to retrieve the next page of results. For the first request, do not specify this parameter. The token can be 1 to 2,048 bytes in length.
returnData	Boolean	No	false	Specifies whether to return the vector data. Valid values: true false (default)
returnMetadata	Boolean	No	false	Specifies whether to return the metadata. Valid values: true false (default)
segmentCount	Integer	No	1	Specifies the degree of parallelism for parallel `ListVectors` operations. The value can be up to 16. For serial execution, set this parameter to 1.
segmentIndex	Integer	No	0	When you perform a parallel `ListVectors` operation, the `segmentIndex` value must be less than the `segmentCount` value.
filter	Container	No	N/A	Filters the query results based on metadata. The following limits apply: The total size of the metadata in a filter expression cannot exceed 20 KB. The number of metadata items in a filter expression cannot exceed 1,024. Filter conditions can be nested up to 8 levels deep.

Filter operators

Operator	Supported type	Description
`$eq`	String	Matches the exact value. When used with array-type metadata, this operator returns `true` if the input value matches any element in the array.
`$ne`	String	Not equal to.
`$gt`	Number	Greater than.
`$gte`	Number	Greater than or equal to.
`$lt`	Number	Less than.
`$lte`	Number	Less than or equal to.
`$in`	Array of strings	Matches any value in an array (similar to the SQL `IN` operation)
`$nin`	Array of strings	Does not match any of the values in the array (similar to the SQL `NOT IN` operation)
`$exists`	Boolean	Checks whether a metadata key exists.
`$and`	Array of filter objects	Performs a logical AND operation on an array of two or more filter expressions.
`$or`	Array of filter objects	Performs a logical OR operation on an array of two or more filter expressions.

Response headers

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

Response elements

Parameter	Type	Example	Description
nextToken	String	CAESCG15aC2xxxxx	The query token for the next page of results. If this element is empty, all results have been returned.
vectors	Array of objects	N/A	A list of vector objects.
key	String	doc-001	The primary key of the vector. Parent node: `vectors`
data	Object	N/A	The vector data. This element is returned only when `returnData` is set to `true`. Parent node: `vectors`
metadata	Object	N/A	The metadata of the vector. This element is returned only when `returnMetadata` is set to `true`. Parent node: `vectors`

Examples

Request example

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

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

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

{
   "nextToken": "CAESCG15aC2xxxxx",
   "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"
         }
      }
   ]
}

SDK

The ListVectors operation is available in the following SDKs:

ossutil CLI

For the corresponding ossutil command, see list-vectors.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameter provided in the request is invalid.
MalformedJson	400	The request body contains malformed JSON.
AccessDenied	403	Possible causes: The request does not include user authentication information. You do not have the required permissions for the operation.
NoSuchVectorIndex	404	The specified vector index does not exist.
QpsLimitExceeded	503	The request rate exceeded the QPS limit.