Index 操作
更新时间：2026-08-26
创建索引
接口描述
为指定表和字段新建索引，当前支持新建向量索引、FILTERING索引、二级索引、PERSISTENT_BITMAP索引、PERSISTENT_AGGREGATED_BITMAP索引与倒排索引。支持同时建立多个索引。
请求结构
JSON
1POST /v{version}/index?create HTTP/1.1
2HOST: {Endpoint}
3Authorization: {Authorization}
4{
5 "database": "db_name",
6 "table": "table_name",
7 "indexes": [
8 {
9 "field": "vector_field",
10 "indexName": "vector_idx",
11 "indexType": "HNSW",
12 "metricType": "L2",
13 "params": {
14 "M": 32,
15 "efConstruction": 200
16 },
17 "autoBuild": true,
18 "autoBuildPolicy": {
19 "policyType": "timing",
20 "timing": "2024-01-01 12:00:00"
21 }
22 },
23 {
24 "fields": ["content"],
25 "fieldsIndexAttributes": ["ATTRIBUTE_ANALYZED"],
26 "indexName": "content_inverted_index",
27 "indexType": "INVERTED",
28 "params": {
29 "analyzer": "DEFAULT_ANALYZER",
30 "parseMode": "COARSE_MODE",
31 "analyzerCaseSensitive": false,
32 "stopWords": {
33 "mode": "CUSTOM",
34 "words": ["的", "了", "以及"]
35 }
36 }
37 }
38 ]
39}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
|---|---|---|---|---|
| version | String | 是 | URL参数 | API版本号，当前取1。 |
| database | String | 是 | RequestBody参数 | 指定库的名称。 |
| table | String | 是 | RequestBody参数 | 指定表的名称。 |
| indexes | List Index | 是 | RequestBody参数 | 索引定义详情列表。 |
Index参数
参数结构与Table操作-创建表中的Index参数保持一致。indexType 支持向量索引类型、FILTERING、SECONDARY、PERSISTENT_BITMAP、PERSISTENT_AGGREGATED_BITMAP 和 INVERTED。
向量索引可选填写 truncationDimension，用于指定构建索引时使用的原始向量维度子集。该字段为 Index 顶层参数，与 params 同级，不应填写在 params 内；参数格式、范围和索引类型限制与创建表接口的 Index参数 一致。
当 indexType 为 FILTERING 时，fields[].indexStructureType 支持 DEFAULT、BITMAP 和 AGGREGATED_BITMAP，其中 AGGREGATED_BITMAP 的字段类型限制与创建表接口的 FilteringIndexField 一致。
当 indexType 为 PERSISTENT_BITMAP 时，必须填写 field，字段类型限制与创建表接口的 Index参数 一致。
当 indexType 为 PERSISTENT_AGGREGATED_BITMAP 时，必须填写 field、fanoutBits 和 maxDepth。fanoutBits 取值范围为 [1, 10]，maxDepth 取值范围为 [2, 30]，且需要满足 fanoutBits * (maxDepth - 1) <= 64；字段类型限制与创建表接口的 Index参数 一致。
当 indexType 为 INVERTED 时：
- 必须填写
fields，表示建立倒排索引的字段列表。目前支持TEXT、TEXT_GBK、TEXT_GB18030、ARRAY<TEXT>、JSON类型字段。 - 必须填写
params，支持analyzer、parseMode、analyzerCaseSensitive、stopWords。参数含义、模式组合、词条格式和默认容量限制与创建表时的InvertedIndexParams一致。 - 可选填写
fieldsIndexAttributes，用于指定fields中每个字段的倒排处理方式，顺序必须与fields一致。TEXT、TEXT_GBK、TEXT_GB18030、ARRAY<TEXT>字段支持ATTRIBUTE_ANALYZED、ATTRIBUTE_NOT_ANALYZED；JSON字段支持{"type":"ATTRIBUTE_ANALYZE_JSON_AS_PLAIN_TEXT"}、{"type":"ATTRIBUTE_CONCATENATE_JSON_KV_AS_TERM","concatenateSymbol":"."}。 - 创建索引接口会创建非 legacy 的 LSM 倒排索引。内部参数
legacy不对外开放，用户请求中不应填写。 - 倒排索引创建后会异步构建。构建完成前，查询索引详情中的
state为BUILDING；构建完成后变为NORMAL，此时才可用于 BM25/Hybrid 检索。构建完成前发起检索会返回错误码95（Index Building）。 stopWords只能在创建索引时设置，搜索请求不能临时覆盖，当前也不支持原地修改。未填写stopWords时等价于{"mode":"DEFAULT"}。
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 返回码 |
| msg | String | 返回信息 |
请求示例
JSON
1POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/index?create
2Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
3Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
4{
5 "database": "db_name",
6 "table": "table_name",
7 "indexes": [
8 {
9 "field": "vector_field",
10 "indexName": "vector_idx",
11 "indexType": "HNSW",
12 "metricType": "L2",
13 "params": {
14 "M": 32,
15 "efConstruction": 200
16 }
17 },
18 {
19 "fields": ["content"],
20 "fieldsIndexAttributes": ["ATTRIBUTE_ANALYZED"],
21 "indexName": "content_inverted_index",
22 "indexType": "INVERTED",
23 "params": {
24 "analyzer": "DEFAULT_ANALYZER",
25 "parseMode": "COARSE_MODE",
26 "analyzerCaseSensitive": false,
27 "stopWords": {
28 "mode": "CUSTOM",
29 "words": ["的", "了", "以及"]
30 }
31 }
32 }
33 ]
34}响应示例
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "code": 0,
7 "msg": "Success"
8}查询索引详情
接口描述
查询指定索引的详情。
请求结构
JSON
1POST /v{version}/index?desc HTTP/1.1
2HOST: {Endpoint}
3Authorization: {Authorization}
4{
5 "database": "db_name",
6 "table": "table_name",
7 "indexName": "vector_idx"
8}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
|---|---|---|---|---|
| version | String | 是 | URL参数 | API版本号，当前取1。 |
| database | String | 是 | RequestBody参数 | 指定库的名称。 |
| table | String | 是 | RequestBody参数 | 指定表的名称。 |
| indexName | String | 是 | RequestBody参数 | 指定索引的名称。 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
Index参数
参数结构与Table操作-创建表中的Index参数保持一致。实际返回字段会随索引类型不同而有所差异，除通用字段外，还包括如下内容：
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| indexMajorVersion | Uint64 | 返回当前索引的版本，只在手动rebuild index建索引完成时增加。仅向量索引类型显示。 |
| state | String | 索引状态。取值如下： |
| buildCompletionRate | Float | 向量索引构建完成度，表示已完成向量索引构建的副本数占总副本数的比率。仅向量索引类型显示。 |
| truncationDimension | List Uint32 | 向量索引构建时使用的原始向量维度子集，格式为 [begin, end)。仅在创建表或创建索引时配置后返回，字段位于 Index 顶层，不在 params 内。 |
通过创建索引接口新建的倒排索引会异步构建。state=BUILDING 表示该索引尚不可用于 BM25/Hybrid 检索；state=NORMAL 表示该索引已经完成构建并可用于检索。
不同索引类型的典型返回字段如下：
- 二级索引、PERSISTENT_BITMAP索引、PERSISTENT_AGGREGATED_BITMAP索引：返回
field - FILTERING 索引：返回
fields，其中每个元素包含field和order - 倒排索引：返回
fields、fieldsIndexAttributes，以及params.analyzer、params.parseMode、params.analyzerCaseSensitive、params.stopWords - 向量索引：返回
field、autoBuild、autoBuildPolicy、metricType、params、indexMajorVersion、buildCompletionRate；如配置了truncationDimension，还会返回truncationDimension
倒排索引的 params.stopWords 始终返回 mode。CUSTOM 模式同时返回保持创建顺序的 words；DEFAULT 和 NONE 模式不返回 words。未显式配置停用词的已有索引返回 {"mode":"DEFAULT"}。
其中，autoBuildPolicy 在返回时可能包含如下字段：
policyTypetimingperiodInSecondrowCountIncrementrowCountIncrementRatio
请求示例
JSON
1POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/index?desc
2Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
3Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
4{
5 "database": "db_test",
6 "table": "table_test",
7 "indexName": "vector_idx"
8}响应示例
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "index": {
7 "indexName": "vector_idx",
8 "field": "vector_field",
9 "autoBuild": false,
10 "indexType": "HNSW",
11 "metricType": "L2",
12 "params": {
13 "M": 32,
14 "efConstruction": 200
15 },
16 "state": "NORMAL"
17 },
18 "code": 0,
19 "msg": "Success"
20}倒排索引详情响应示例：
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "index": {
7 "indexName": "content_inverted_index",
8 "indexType": "INVERTED",
9 "fields": ["content"],
10 "fieldsIndexAttributes": ["ATTRIBUTE_ANALYZED"],
11 "params": {
12 "analyzer": "DEFAULT_ANALYZER",
13 "parseMode": "COARSE_MODE",
14 "analyzerCaseSensitive": false,
15 "stopWords": {
16 "mode": "CUSTOM",
17 "words": ["的", "了", "以及"]
18 }
19 },
20 "state": "BUILDING"
21 },
22 "code": 0,
23 "msg": "Success"
24}重建索引
接口描述
重建指定索引，仅支持重建向量索引。
请求结构
JSON
1POST /v{version}/index?rebuild HTTP/1.1
2HOST: {Endpoint}
3Authorization: {Authorization}
4{
5 "database": "db_name",
6 "table": "table_name",
7 "indexName": "vector_idx"
8} 请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
|---|---|---|---|---|
| version | String | 是 | URL参数 | API版本号，当前取1。 |
| database | String | 是 | Request Body参数 | 指定库的名称。 |
| table | String | 是 | Request Body参数 | 指定表的名称。 |
| indexName | String | 是 | Request Body参数 | 指定索引的名称。 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 返回码 |
| msg | String | 返回信息 |
请求示例
JSON
1POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/index?rebuild
2Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
3Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
4{
5 "database": "db_test",
6 "table": "table_test",
7 "indexName": "vector_idx"
8}响应示例
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "code": 0,
7 "msg": "Success"
8}删除索引
接口描述
删除指定索引。
请求结构
JSON
1DELETE /v{version}/index HTTP/1.1
2HOST: {Endpoint}
3Authorization: {Authorization}
4{
5 "database": "db_name",
6 "table": "table_name",
7 "indexName": "index_name"
8}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
|---|---|---|---|---|
| version | String | 是 | URL参数 | API版本号，当前取1。 |
| database | String | 是 | RequestBody参数 | 指定库的名称。 |
| table | String | 是 | RequestBody参数 | 指定表的名称。 |
| indexName | String | 是 | RequestBody参数 | 指定索引的名称。 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 返回码 |
| msg | String | 返回信息 |
请求示例
JSON
1DELETE http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/index
2Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
3Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
4{
5 "database": "db_test",
6 "table": "table_test",
7 "indexName": "vector_idx"
8}响应示例
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "code": 0,
7 "msg": "Success"
8}修改索引
接口描述
修改向量索引信息。当前对外仅支持修改 autoBuild 和 autoBuildPolicy。
请求结构
JSON
1POST /v{version}/index?modify HTTP/1.1
2HOST: {Endpoint}
3Authorization: {Authorization}
4{
5 "database": "db_name",
6 "table": "table_name",
7 "index": {
8 "indexName": "vector_idx",
9 "autoBuild": true,
10 "autoBuildPolicy": {
11 "policyType": "PERIODICAL",
12 "periodInSecond": 5000,
13 "timing": "2026-01-01 12:00:00"
14 }
15 }
16}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
|---|---|---|---|---|
| version | String | 是 | URL参数 | API版本号，当前取1。 |
| database | String | 是 | RequestBody参数 | 指定库的名称。 |
| table | String | 是 | RequestBody参数 | 指定表的名称。 |
| index | Index | 是 | RequestBody参数 | 索引定义详情。 |
Index参数
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| indexName | String | 索引名称，要求表内唯一。索引名称的命名要求如下： 1. 仅支持大小写字母、数字以及下划线（_），必须以字母开头； 2. 长度限制为1~255。 |
| autoBuild | Boolean | 是否自动构建索引。 |
| autoBuildPolicy | AutoBuildPolicy | 构建索引策略；当 autoBuild=true 时可配置。 |
AutoBuildPolicy
| 参数名称 | 类型 | 描述 |
|---|---|---|
| policyType | String | 自动构建索引策略类型，大小写不敏感，支持的类型如下： |
| timing | String | |
| periodInSecond | Uint64 | 周期性构建索引的参数，每过periodInSecond构建一次索引，只在policyType为periodical时生效。可以指定从某个时间点开始，通过上面的timing参数传入。周期不能低于3600 |
| rowCountIncrement | Uint64 | 当tablet（不是table）增加或者减少行数大于rowCountIncrement时构建一次索引，只在policyType为row_count_increment时生效。不能低于10000 |
| rowCountIncrementRatio | double | 当tablet增加或者减少行数百分比大于rowCountIncrementRatio时构建一次索引，只在policyType为row_count_increment时生效。不能小于等于0 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 返回码 |
| msg | String | 返回信息 |
请求示例
JSON
1POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/index?modify
2Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
3Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
4{
5 "database": "db_name",
6 "table": "table_name",
7 "index": {
8 "indexName": "vector_idx",
9 "autoBuild": true,
10 "autoBuildPolicy": {
11 "policyType": "PERIODICAL",
12 "periodInSecond": 5000,
13 "timing": "2026-01-01 12:00:00"
14 }
15 }
16}响应示例
JSON
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
5{
6 "code": 0,
7 "msg": "Success"
8}评价此篇文章