文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>向量数据库>SDK 参考>HTTP API>Index>rebuild

rebuild

最近更新时间：2025-11-06 10:20:32

我的收藏

本页目录：

本接口（/index/rebuild）用于重建指定 Base 类数据库 Collection 的所有索引，清除无用的索引数据，修复损坏的索引数据，优化索引结构，改善性能。
说明：
rebuild 接口用于重建指定集合的向量索引，主要适用于以下两种场景：
首次使用 IVF 系列（含 IVF_RABITQ 索引）索引时，需要通过 rebuild 接口初始化索引结构。具体信息，请参见 IVF 系列索引应用指南。
在离线批量数据导入场景中，建议先执行数据写入操作（通过 upsert 接口设置 buildIndex=false暂停索引构建），待数据完整导入后，再调用rebuild 接口集中创建索引，以此减少写入过程中的索引维护开销，提升整体导入效率。

Method 与 URL

POST https://{实例访问 IP 地址}:{实例网络端口}/index/rebuild
警告：
Rebuild 操作需占用额外内存且可能影响服务，执行前请评估业务场景并选择重建方式。
保留原索引、同时构建新索引（即设置 dropBeforeRebuild=False）：期间集合读取正常，写入被阻止，构建新索引后，替换原索引，构建过程中，旧索引和新索引都会占用内存，如果内存足够可采用该方式，建议根据实际业务高低峰选择停写时段执行。
先删除原索引、再构建新索引（即设置 dropBeforeRebuild=True）：期间集合读写会受到影响，先删除旧索引，再构建新索引。如果内存严重不足时，则需采用该方案。建议根据业务需求选择可中断服务的时段处理。

使用示例

注意：
如下示例可直接复制，在 CVM 运行之前，您需在文本编辑器将 api_key=A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X 依据实际情况进行替换。 
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/index/rebuild  \\
 -d '{
    "database": "db-test",
    "collection": "book-vector",
    "dropBeforeRebuild": true,
    "throttle": 1
}'

请求参数

参数
是否必选
参数含义
配置方法及要求
database
是
指定需重建索引的 Database 名称。
使用 /database/list 获取集群中的数据库列表，复制需重建索引的集合所属的数据库名。
collection
是
指定需重建索引的 Collection 名称。
使用 /collection/list 获取指定数据库名下的 Collection 列表，复制需重建索引的集合名。
fieldName
是
指定重建索引的字段。
vector：重建稠密向量索引。
sparse_vector：重建稀疏向量索引。
说明：
同一集合，不支持并发执行 rebuild。如果集合中既有稠密向量又有稀疏向量，则需要分别进行重建。
dropBeforeRebuild
否
标识在重建索引时，是否需先删除旧索引再重建新索引。
警告：
重建索引需要占用额外的内存空间，数据量越大，消耗的内存空间越大。在重建索引之前，您需根据实际资源情况选择是否需先删除旧索引再重建，避免引起内存占满而阻塞业务正常运行。
取值如下所示：
true：重建之前，先删除旧索引再重建索引。
警告：
内存资源不足时，可配置为 true，先删除旧索引，在新索引构建过程中，无法正常读写。
false：重建之前，不删除旧索引，创建新索引完成之后再删除旧索引。默认为 false。
警告：
内存资源足够的情况下，可配置为 false，可不删除旧索引。在新索引构建过程中，可读数据，禁止写入数据。
throttle
否
标识是否限制构建索引的单节点 CPU 核数。
说明：
重建索引会消耗 CPU 资源，为防止资源打满影响写入或者检索等操作，请根据业务实际配置重建索引的 CPU 核数。默认为限制 CPU 核数为1。
取值如下所示：
0：不限制 CPU 核数。
1~节点 CPU 核数：可用于 rebuild 的 CPU 资源最大为实例单个节点规格的 CPU 核数。

响应消息

HTTP 响应消息体是服务器返回给客户端的数据，通常包含了请求的结果或者所请求的资源。/index/rebuild 接口返回的状态码以及相关信息，如下表所示。
状态码
含义
响应信息
200
创建成功
{
  "code": 0,
  "msg": "operation success"
}
400
创建失败
{
  "code": 1,
  "msg": "operation failed, reason...."
}

相关说明

调用/index/rebuild重建索引之后，请使用 /collection/describe 接口查看 Collection 的索引状态。当返回参数 indexStatus 中的 status 显示为 ready 时，说明索引重构完成，可正常写入数据。
initial：索引已创建但尚未构建，处于初始状态。
ready：索引构建成功且已就绪，可正常执行操作。
training：正在训练机器学习模型以生成向量数据。
building：正在构建向量索引结构并存储向量数据。
building_scalar：正在构建标量索引。
building_sparse：正在构建稀疏向量索引。
failed：索引构建失败，需修复后方可正常操作。
{
    "code": 0,
    "msg": "operation success",
    "collection": {
        "database": "db-test",
        "collection": "coll-test",
        "documentCount": 4,
        "indexes": [
           ......
        ],
        "indexStatus": {
            "status": "ready",
            "startTime": ""
        }
    }
}
中国站
目录