金山云-文档中心-List Vectors

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

向量相关

List Vectors

最近更新时间：2026-11-03 19:52:57



描述

列举向量索引中的所有向量数据。使用此接口，您必须是这个 Bucket 的拥有者或拥有 ks3:ListVectors 权限。通过设置 segmentCount 和 segmentIndex 参数，可并行列举向量以加快遍历速度。

单次 ListVectors 请求最多返回 1000 条向量数据;若列举的向量在达到指定数量前超过 1MB，请求会提前截断并返回已列举的向量。

请求

请求语法

POST /ListVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: GMT Date
Content-Type: application/json
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

方式一：使用索引资源标识 indexKrn 指定目标索引。

{
   "indexKrn": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int
}

方式二：使用 indexName + vectorBucketName 组合指定目标索引。

{
   "indexName": "string",
  "vectorBucketName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int
}

请求参数

该接口不使用请求参数。

请求头

该接口仅使用公共请求头。

请求体

segmentCount 与 segmentIndex 必须同时提供或同时省略：只提供其中一个返回 400 SegmentParamsIncomplete；segmentIndex 大于 segmentCount 返回 400 InvalidSegmentIndex。

参数	是否必填	类型	说明
indexKrn	否（与 `indexName` + `vectorBucketName` 二选一，必选其一）	String	向量索引资源名，格式为 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>/index/<indexName>`。AWS4 签名下字段名为 `indexArn`。
indexName	否（与 `vectorBucketName` 成组使用，与 `indexKrn` 二选一）	String	向量索引名称。长度为 3~63 字符，仅允许小写字母和数字，首字符必须是字母。
vectorBucketName	否（与 `indexName` 成组使用，与 `indexKrn` 二选一）	String	向量存储桶名称。长度为 3~63 字符，允许小写字母、数字和 `-`，首尾不能是 `-`。
maxResults	否	Integer	单次返回的最大向量数量，取值范围 1~1000，默认 500。
nextToken	否	String	分页凭证，取值为上一次 ListVectors 响应返回的 `nextToken`；首次调用时为空。
returnData	否	Boolean	是否返回向量数据，默认 `false`。
returnMetadata	否	Boolean	是否返回向量元数据，默认 `false`。
segmentCount	否	Integer	并行列举时划分的段数，取值范围 1~16，取 1 表示串行列举。必须与 `segmentIndex` 同时提供或同时省略。
segmentIndex	否	Integer	当前请求列举的段索引，1-based，取值范围 1~`segmentCount`。必须与 `segmentCount` 同时提供或同时省略。

响应

响应头

该接口仅返回公共响应头。

响应体

{
   "nextToken": "string",
   "vectors": [ 
      { 
         "key": "string",
         "data": { ... },
         "metadata": JSON value
      }
   ]
}

请求成功，该接口请求返回 HTTP 200状态码，并以 JSON 格式返回响应数据。

名称	父节点	描述	类型
nextToken	无	分页凭证，用于下一次请求。当本页返回条数达到 `maxResults` 时，响应可能包含 `nextToken`；返回条数小于 `maxResults` 或列表为空表示已列举完毕。	String
vectors	无	列举出的向量	Array

vectors 的内容：

名称	父节点	描述	类型
key	vectors	向量主键	String
data	vectors	条件返回：仅当 `returnData=true` 时返回；为 `false` 时该字段整体不出现（不是 `null`）	VectorData
metadata	vectors	条件返回：仅当 `returnMetadata=true` 时返回；为 `false` 时该字段整体不出现（不是 `null`）	JSON

data 的内容：

名称	父节点	描述	类型
float32	vectors.data	float32 类型的向量数据	Array

示例

案例一：串行列举向量数据

请求示例:

POST /ListVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 45
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=****************************************

{
  "indexName": "exampleindex",
  "vectorBucketName": "example-bucket",
  "maxResults": 2,
  "returnData": true,
  "returnMetadata": true
}

响应示例:

HTTP/1.1 200 OK
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 100
Connection: close
X-kss-Request-Id: MTg4NWYxZTQ2YTNmOTMyOF*************

{
  "nextToken": "IWE1KiEsPSc4Z3lmemBjamNnPyw0OTo8OgkmLCEhJn1JAh*************************",
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0]
      },
      "metadata": {
        "color": "red",
        "count": 10
      }
    },
    {
      "key": "key-2",
      "data": {
        "float32": [3.0, 4.0]
      },
      "metadata": {
        "color": "blue",
        "count": 20
      }
    }
  ]
}

案例二：并行列举向量数据

请求示例：

POST /ListVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 45
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=****************************************


{
  "indexName": "exampleindex",
  "vectorBucketName": "example-bucket",
  "maxResults": 2,
  "returnData": true,
  "segmentCount": 4,
  "segmentIndex": 3
}

响应示例：

HTTP/1.1 200 OK
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 100
Connection: close
X-kss-Request-Id: MTg4NWYxZTQ2YTNmOTMyOF*************

{
  "nextToken": "IWE1KiEsPSc4Z3lmemBjamNnPyw0OTo8OgkmLCEhJn1JAh*************************",
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0]
      }
    },
    {
      "key": "key-2",
      "data": {
        "float32": [3.0, 4.0]
      }
    }
  ]
}

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求不合法	`maxResults` 不在 1~1000 内；`segmentCount` 或 `segmentIndex` 不在 1~16 内；只提供其中一个分段参数；`segmentIndex` 大于 `segmentCount`；`nextToken` 非法；资源标识冲突或缺失。
403	AccessDeniedException	访问被拒绝	无 `ks3:ListVectors` 权限，或被桶策略拒绝。
404	NotFoundException	资源不存在	指定的向量桶或向量索引不存在。
500	InternalServerException	服务内部错误	服务内部异常。

具体错误码通过响应头 x-kss-error-code 返回。

错误响应体格式如下，fieldList 仅校验类错误携带；非校验类错误只返回 message：

{"message": "The indexName is invalid.", "fieldList": [{"path": "/indexName", "message": "indexName must be 3-63 characters, only lowercase letters and digits, starting with a lowercase letter."}]}

文档导读

上一篇：Get Vectors

下一篇：Delete Vectors

纯净模式常规模式

纯净模式

点击可全屏预览文档内容