Index 操作
更新时间:2026-09-01
创建索引
功能介绍
为指定表和指定字段新建索引,当前支持新建向量索引、FILTERING索引、二级索引、PERSISTENT_BITMAP索引、PERSISTENT_AGGREGATED_BITMAP索引与倒排索引(全文索引),支持一次请求同时创建多个索引。
C++ SDK 通过mochow::Table::CreateIndexes提交,索引定义复用建表使用的mochow::Index。
请求示例
C++
1#include <iostream>
2#include <memory>
3#include <vector>
4
5#include "mochow/Mochow.h"
6
7int main() {
8 mochow::ClientOptions options;
9 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
10 options.credentials.account = "root";
11 options.credentials.api_key = "$您的账户API密钥";
12
13 auto client_result = mochow::MochowClient::Create(options);
14 if (!client_result.IsOk()) {
15 std::cerr << "create client failed: "
16 << client_result.GetStatus().Message() << std::endl;
17 return 1;
18 }
19 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
20 mochow::Database db = client->GetDatabase("db_test");
21 mochow::Table table = db.GetTable("book_vector");
22
23 std::vector<mochow::Index> indexes = {
24 // 向量索引
25 mochow::Index::Hnsw("vector_idx",
26 "vector",
27 mochow::MetricType::L2,
28 mochow::HnswParams{32, 200})
29 .AutoBuild(true)
30 .AutoBuildPolicy(mochow::AutoBuildPolicy::Periodical(
31 24 * 3600, "2026-01-01 12:00:00")),
32 // 标量二级索引
33 mochow::Index::Secondary("book_name_idx", "bookName"),
34 // FILTERING 索引,AGGREGATED_BITMAP 结构可加速范围过滤
35 mochow::Index::FilteringWithFields(
36 "publish_time_filtering",
37 {mochow::FilteringIndexField(
38 "publishTime",
39 mochow::FilteringIndexStructureType::AggregatedBitmap)}),
40 // 持久化 BITMAP / AGGREGATED_BITMAP 索引
41 mochow::Index::PersistentBitmap("region_bitmap", "region"),
42 mochow::Index::PersistentAggregatedBitmap(
43 "views_aggregated_bitmap",
44 "views",
45 mochow::PersistentAggregatedBitmapParams{4, 12}),
46 };
47
48 mochow::Status status = table.CreateIndexes(indexes);
49 if (!status.IsOk()) {
50 std::cerr << "create indexes failed: " << status.Message()
51 << ", request_id=" << status.RequestId() << std::endl;
52 return 1;
53 }
54
55 (void)client->Close();
56 return 0;
57}
请求参数
| 参数 | 参数类型 | 是否必选 | 参数含义 |
|---|---|---|---|
| indexes | const std::vector<mochow::Index>& | 是 | 索引定义列表,不能为空。 |
| options | mochow::RequestOptions | 否 | 单次请求级选项,可设置WithRequestId、WithRequestTimeoutMs、WithIdempotencyKey和WithRetry。 |
Index参数
请参见建表操作的Index参数、向量索引参数、标量索引参数、倒排索引参数描述。
注意事项
- 创建FILTERING索引时,
FilteringIndexField::StructureType支持Default、Bitmap和AggregatedBitmap;AggregatedBitmap除等值过滤外,还可加速>、>=、<、<=范围过滤。 - 创建PERSISTENT_AGGREGATED_BITMAP索引时必须填写
fanout_bits和max_depth,取值范围分别为[1, 10]和[2, 30],且需要满足fanout_bits * (max_depth - 1) <= 64;SDK 在编码请求时本地校验,不满足时返回StatusCode::InvalidArgument。 - 创建倒排索引(全文索引)时,
fields支持TEXT、TEXT_GBK、TEXT_GB18030、ARRAY<TEXT>、JSON类型字段;InvertedIndexParams中的StopWords只能在创建索引时指定,创建后不支持原地修改,检索请求也不能临时覆盖。 - 指定
field_attributes时,其长度必须与fields长度一致,否则 SDK 返回StatusCode::InvalidArgument。 - 倒排索引创建后会异步构建:构建完成前查询索引详情返回的
state为BUILDING,此时发起BM25/Hybrid检索会返回错误码95(Index Building);state变为NORMAL后方可用于检索。
全文索引创建示例
C++
1#include <chrono>
2#include <iostream>
3#include <memory>
4#include <thread>
5#include <vector>
6
7#include "mochow/Mochow.h"
8
9int main() {
10 mochow::ClientOptions options;
11 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
12 options.credentials.account = "root";
13 options.credentials.api_key = "$您的账户API密钥";
14
15 auto client_result = mochow::MochowClient::Create(options);
16 if (!client_result.IsOk()) {
17 std::cerr << "create client failed: "
18 << client_result.GetStatus().Message() << std::endl;
19 return 1;
20 }
21 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
22 mochow::Database db = client->GetDatabase("db_test");
23 mochow::Table table = db.GetTable("book_segments");
24
25 mochow::Index inverted_index = mochow::Index::Inverted(
26 "segment_inverted_idx",
27 {"segment"},
28 mochow::InvertedIndexParams()
29 .Analyzer(mochow::InvertedIndexAnalyzer::Default)
30 .ParseMode(mochow::InvertedIndexParseMode::Coarse)
31 .CaseSensitive(true)
32 .StopWords(mochow::StopWordsParams(mochow::StopWordsMode::Custom,
33 {"呀", "啊", "哦"})),
34 {mochow::InvertedIndexFieldAttribute::Analyzed});
35
36 mochow::Status status = table.CreateIndexes({inverted_index});
37 if (!status.IsOk()) {
38 std::cerr << "create inverted index failed: " << status.Message()
39 << std::endl;
40 return 1;
41 }
42
43 // 倒排索引异步构建,等待 state 变为 NORMAL 后才能发起 BM25/Hybrid 检索
44 for (int i = 0; i < 60; ++i) {
45 mochow::IndexInfo index_info;
46 status = table.DescribeIndex("segment_inverted_idx", &index_info);
47 if (!status.IsOk()) {
48 std::cerr << "describe index failed: " << status.Message()
49 << std::endl;
50 return 1;
51 }
52 if (index_info.state == "NORMAL") {
53 break;
54 }
55 std::this_thread::sleep_for(std::chrono::seconds(2));
56 }
57
58 (void)client->Close();
59 return 0;
60}
删除索引
功能介绍
删除指定索引,支持删除向量索引、标量索引与倒排索引(含2.4之前版本创建的全文索引)。当前不支持删除构建中(state为BUILDING)的向量索引与倒排索引。
请求示例
C++
1#include <iostream>
2#include <memory>
3
4#include "mochow/Mochow.h"
5
6int main() {
7 mochow::ClientOptions options;
8 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
9 options.credentials.account = "root";
10 options.credentials.api_key = "$您的账户API密钥";
11
12 auto client_result = mochow::MochowClient::Create(options);
13 if (!client_result.IsOk()) {
14 std::cerr << "create client failed: "
15 << client_result.GetStatus().Message() << std::endl;
16 return 1;
17 }
18 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
19 mochow::Database db = client->GetDatabase("db_test");
20 mochow::Table table = db.GetTable("book_vector");
21
22 mochow::Status status = table.DropIndex("vector_idx");
23 if (!status.IsOk()) {
24 std::cerr << "drop index failed: " << status.Message() << std::endl;
25 return 1;
26 }
27
28 (void)client->Close();
29 return 0;
30}
请求参数
| 参数 | 参数类型 | 是否必选 | 参数含义 |
|---|---|---|---|
| index_name | const std::string& | 是 | 指定索引的名称,不能为空。 |
| options | mochow::RequestOptions | 否 | 单次请求级选项。 |
重建向量索引
功能介绍
重建指定索引,当前仅支持重建向量索引。重建为异步过程,可通过查询索引详情观察state与build_completion_rate。
请求示例
C++
1#include <chrono>
2#include <iostream>
3#include <memory>
4#include <thread>
5
6#include "mochow/Mochow.h"
7
8int main() {
9 mochow::ClientOptions options;
10 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
11 options.credentials.account = "root";
12 options.credentials.api_key = "$您的账户API密钥";
13
14 auto client_result = mochow::MochowClient::Create(options);
15 if (!client_result.IsOk()) {
16 std::cerr << "create client failed: "
17 << client_result.GetStatus().Message() << std::endl;
18 return 1;
19 }
20 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
21 mochow::Database db = client->GetDatabase("db_test");
22 mochow::Table table = db.GetTable("book_vector");
23
24 mochow::Status status = table.RebuildIndex("vector_idx");
25 if (!status.IsOk()) {
26 std::cerr << "rebuild index failed: " << status.Message() << std::endl;
27 return 1;
28 }
29
30 for (int i = 0; i < 90; ++i) {
31 mochow::IndexInfo index_info;
32 status = table.DescribeIndex("vector_idx", &index_info);
33 if (!status.IsOk()) {
34 std::cerr << "describe index failed: " << status.Message()
35 << std::endl;
36 return 1;
37 }
38 if (index_info.state == "NORMAL") {
39 break;
40 }
41 std::this_thread::sleep_for(std::chrono::seconds(1));
42 }
43
44 (void)client->Close();
45 return 0;
46}
请求参数
| 参数 | 参数类型 | 是否必选 | 参数含义 |
|---|---|---|---|
| index_name | const std::string& | 是 | 向量索引的名称,不能为空。 |
| options | mochow::RequestOptions | 否 | 单次请求级选项。 |
查询索引详情
功能介绍
查询指定索引的详情,返回索引定义、当前状态以及(向量索引)构建进度。
请求示例
C++
1#include <iostream>
2#include <memory>
3
4#include "mochow/Mochow.h"
5
6int main() {
7 mochow::ClientOptions options;
8 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
9 options.credentials.account = "root";
10 options.credentials.api_key = "$您的账户API密钥";
11
12 auto client_result = mochow::MochowClient::Create(options);
13 if (!client_result.IsOk()) {
14 std::cerr << "create client failed: "
15 << client_result.GetStatus().Message() << std::endl;
16 return 1;
17 }
18 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
19 mochow::Database db = client->GetDatabase("db_test");
20 mochow::Table table = db.GetTable("book_vector");
21
22 mochow::IndexInfo index_info;
23 mochow::Status status = table.DescribeIndex("vector_idx", &index_info);
24 if (!status.IsOk()) {
25 std::cerr << "describe index failed: " << status.Message() << std::endl;
26 return 1;
27 }
28
29 std::cout << "index: " << index_info.index.Name()
30 << ", field: " << index_info.index.FieldName()
31 << ", auto_build: " << index_info.index.AutoBuild()
32 << ", state: " << index_info.state << std::endl;
33 if (index_info.has_build_completion_rate) {
34 std::cout << "build_completion_rate: "
35 << index_info.build_completion_rate << std::endl;
36 }
37
38 (void)client->Close();
39 return 0;
40}
请求参数
| 参数 | 参数类型 | 是否必选 | 参数含义 |
|---|---|---|---|
| index_name | const std::string& | 是 | 指定索引的名称,不能为空。 |
| index | mochow::IndexInfo* | 是 | 输出参数,用于接收索引详情,不能为空指针。 |
| options | mochow::RequestOptions | 否 | 单次请求级选项。 |
返回参数
IndexInfo参数
| 参数 | 参数类型 | 参数含义 |
|---|---|---|
| index | mochow::Index | 索引定义对象,字段访问方法见Index返回字段。 |
| state | std::string | 索引状态。取值如下: |
| build_completion_rate | double | 向量索引的构建完成度,仅当服务端返回该字段时有效。 |
| has_build_completion_rate | bool | 标识build_completion_rate是否有效。 |
Index返回字段
| 参数 | 参数类型 | 参数含义 |
|---|---|---|
| Name() | const std::string& | 索引名称。 |
| Type() | mochow::IndexType | 索引类型,取值见建表操作的Index参数。 |
| FieldName() | const std::string& | 索引作用于的字段名称。二级索引、PERSISTENT_BITMAP索引、PERSISTENT_AGGREGATED_BITMAP索引与向量索引返回该字段。 |
| Fields() | const std::vector<std::string>& | 索引作用于的字段名称列表。FILTERING索引与倒排索引返回该字段。 |
| FilteringFields() | const std::vector<mochow::FilteringIndexField>& | FILTERING索引的字段级配置,可通过Field()、HasStructureType()、StructureType()读取。 |
| Metric() | std::optional<mochow::MetricType> | 向量索引的距离度量类型,非向量索引为空。 |
| Params() | const std::map<std::string, mochow::FieldValue>& | 向量索引构建参数,键名与HTTP协议一致,如M、efConstruction、nlist、qtBits、NSQ。 |
| AutoBuild() | bool | 向量索引是否配置了自动构建策略。 |
| AutoBuildPolicyConfig() | const mochow::AutoBuildPolicy& | 自动构建策略,可通过Type()、Timing()、PeriodSeconds()、RowCountIncrement()、RowCountIncrementRatio()读取。 |
| HasRuleBased() / RuleBasedConfig() | bool / const mochow::RuleBasedIndexParams& | 规则隔离索引配置,包含isolated_field与threshold。 |
| PersistentAggregatedBitmapParamsConfig() | const mochow::PersistentAggregatedBitmapParams& | 持久化AGGREGATED_BITMAP索引的fanout_bits与max_depth;服务端未返回时保持默认值0。 |
| FieldAttributes() | const std::vector<mochow::InvertedIndexFieldAttribute>& | 倒排索引各字段的分词处理方式,顺序与Fields()一致。 |
| InvertedParams() | const mochow::InvertedIndexParams& | 倒排索引参数,可通过HasAnalyzer()/Analyzer()、HasParseMode()/ParseMode()、CaseSensitive()、HasStopWords()/StopWords()读取。 |
注:倒排索引的停用词始终返回mode;Custom模式同时返回保持创建顺序的words,Default和None模式不返回words;未显式配置停用词的已有索引返回Default模式。
修改索引
功能介绍
修改向量索引信息,目前只支持修改autoBuild属性及其自动构建策略。
请求示例
C++
1#include <iostream>
2#include <memory>
3
4#include "mochow/Mochow.h"
5
6int main() {
7 mochow::ClientOptions options;
8 options.endpoint = "http://127.0.0.1:5287"; // $您的实例访问端点
9 options.credentials.account = "root";
10 options.credentials.api_key = "$您的账户API密钥";
11
12 auto client_result = mochow::MochowClient::Create(options);
13 if (!client_result.IsOk()) {
14 std::cerr << "create client failed: "
15 << client_result.GetStatus().Message() << std::endl;
16 return 1;
17 }
18 std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
19 mochow::Database db = client->GetDatabase("db_test");
20 mochow::Table table = db.GetTable("book_vector");
21
22 mochow::ModifyIndexRequest modify_index;
23 modify_index.WithIndexName("vector_idx")
24 .WithAutoBuild(true)
25 .WithAutoBuildPolicy(
26 mochow::AutoBuildPolicy::Timing("2026-06-06 00:00:00"));
27
28 mochow::Status status = table.ModifyIndex(modify_index);
29 if (!status.IsOk()) {
30 std::cerr << "modify index failed: " << status.Message() << std::endl;
31 return 1;
32 }
33
34 (void)client->Close();
35 return 0;
36}
请求参数
ModifyIndexRequest参数
| 参数 | 参数类型 | 是否必选 | 参数含义 |
|---|---|---|---|
| WithIndexName | std::string | 是 | 向量索引的名称,不能为空。 |
| WithAutoBuild | bool | 是 | 是否自动构建索引,默认值为false。 |
| WithAutoBuildPolicy | mochow::AutoBuildPolicy | 否 | 自动构建索引策略,仅在WithAutoBuild(true)时下发。当前支持如下策略:AutoBuildPolicy::Timing:定时构建,指定构建时间,只构建一次,不会重复构建,时间格式支持UTC及LOCALAutoBuildPolicy::Periodical:周期性构建,每过period_seconds秒构建一次索引,可重复构建,周期不能低于3600,可指定起始时间AutoBuildPolicy::RowCountIncrement:增量行数构建,Tablet(不是table)增加或减少指定行数时自动构建一次索引,可重复构建,支持具体行数以及百分比,增量行数不低于10000,增量行数百分比需要大于0 |
评价此篇文章
