flexsearch4cj Index 单字段索引实战:增删改查 4 大核心操作一次看懂
flexsearch4cj Index 单字段索引实战:增删改查 4 大核心操作一次看懂
flexsearch4cj 是一个快速、零依赖的全文搜索库,其中的 Index 单字段索引负责最核心的"增删改查"四大操作:add/append 添加、search 查询、update 更新、remove 删除。本文将带你用最短路径跑通这套 Index 索引 API,无需任何外部依赖,几行代码就能给应用加上全文搜索能力。
上面是 flexsearch4cj 的核心模块分层示意,Index 就运行在 core 层之上,所有增删改查都围绕这个索引对象展开。
Index 是什么:单字段索引的定位
Index 是 flexsearch4cj 提供的单字段索引类:每条数据由一个唯一的 id 加一段 content 文本组成,库内部会自动分词、建立倒排结构。相比 Document 多字段索引,Index 更轻量,适合只搜索单一文本列的场景,比如:
- 商品名称搜索
- 用户名/昵称检索
- 文章标题索引
完整的接口定义位于 index.cj,API 说明参考官方文档 doc/feature_api.md。
第一步:用 Preset 预设初始化索引
新手最省心的做法是直接取 Preset 预设模板(共 5 种:MEMORY / PERFORMANCE / MATCH / SCORE / DEFAULT),它内部封装了分词、评分等参数的合理默认值,见 index_options.cj:
import flexsearch.*
var options = Preset.DEFAULT.getIndexOptions()
var index = Index(options)
如果后续想调整分词模式(tokenize)、最小词长(minlength)等,直接修改这个 options 对象再传入构造即可。
操作一:增 —— add 与 append 把数据写进索引
写入数据有两个方法,语义不同,是新手最容易混淆的点:
| 方法 | 行为 | 适用场景 |
|---|---|---|
add(id, content) |
写入新数据;若 id 已存在,自动转为更新 | 常规新增/覆盖 |
append(id, content) |
向已有 id 追加文本内容 | 流式拼接内容 |
index.add("26", "z zz zzz") // 新增一条索引
index.append("52", "appendIndex") // 向 id=52 的内容末尾追加
两个细节值得记住:
- 返回的都是
Index对象本身,支持链式调用; id或content为空字符串时会被静默跳过,不会抛异常(见 index.cj)。
操作二:查 —— search 按条件检索 id
search 是查询入口,返回命中的 id 列表(ArrayList<String>),支持多词查询与选项控制:
var result: ArrayList<String> = index.search(querys: "z zz zzz")
通过 IndexSearchOptions 可以控制查询行为,默认值已经很适合新手直接使用:
limit:返回条数上限,默认100offset:结果起始位置,默认0(可实现分页)suggest:是否开启建议(模糊容错)模式,默认false
var opt = IndexSearchOptions()
opt.limit = 10
opt.offset = 0
index.search(querys: "zz", options: opt)
内部实现上,查询会先按 minlength 过滤并去重查询词,再通过倒排结构取交集,详见 index.cj。
操作三:改 —— update 一行完成"删旧加新"
更新非常简单,update 等价于"先 remove 再 add":
index.update("52", "updateIndex") // 按 id 更新内容
实现见 index.cj,只有两行:先删除旧记录,再写入新内容,保证索引中不存在脏数据。
💡 小技巧:
add遇到已存在的 id 时也会自动走更新逻辑,所以日常开发中"覆盖写"直接用add就够了。
操作四:删 —— remove 删除 + contain 判断存在
删除按 id 精确定位,同时会清理缓存与倒排中的引用:
index.remove("26") // 删除 id=26 的数据
var exists: Bool = index.contain("26") // 判断某条数据是否还在
contain 是配套的存在性检查方法,适合在删除前做校验,避免误删。删除的实现位于 index.cj。
四大核心操作速查表
| 操作 | 方法 | 参数 | 返回值 |
|---|---|---|---|
| 增 | add / append |
id, content |
Index |
| 查 | search |
querys, options(可选) |
ArrayList<String> |
| 改 | update |
id, content |
Index |
| 删 | remove |
id |
Index |
| 判存在 | contain |
id |
Bool |
进阶:Async 异步版本让索引不阻塞
数据量大时,flexsearch4cj 为每个核心操作都提供了异步版本,在独立线程中执行,不会阻塞 UI:
index.addAsync("26", "z zz zzz")
index.removeAsync("26")
index.updateAsync("52", "updateIndex")
index.searchAsync(querys: "appendIndex")
所有 *Async 方法返回 Future,也可以传入回调函数在完成后执行后续逻辑,方法定义见 index.cj。
小结
Index是 flexsearch4cj 的单字段全文搜索核心,用Preset.DEFAULT.getIndexOptions()初始化即可上手;- 四大操作一一对应:
add/append增、search查、update改、remove删,另有contain做存在判断; - 需要非阻塞执行时,全部换成对应的
*Async方法即可。
掌握以上四步,你就能在仓颉项目中快速搭建起一套轻量的全文搜索能力了。

