IndexedDB 的高效查询依赖 B+ 树索引、事务隔离、键路径映射与游标遍历协同工作;索引是独立 B+ 树副本,叶子节点仅存主键;复合索引字段顺序决定可支持的查询模式;所有查询须在事务内执行,readonly 事务提供快照一致性。

IndexedDB 的索引与查询不是“自动加速”的魔法,而是基于明确的数据结构设计和底层机制协同工作的结果。它的高效,来自 B+ 树索引、事务隔离、键路径映射与游标遍历四者的紧密配合。
索引本质是独立的 B+ 树副本
每个索引(IDBIndex)并非对主数据的简单标记,而是在底层维护一份独立的、按索引字段排序的 B+ 树结构。该树的叶子节点不存完整记录,只存“主键值”(即对象存储中该记录的 key),并按索引字段升序排列。这意味着:
- 查询
emailIndex.get("user@x.com")实际是在 email 索引的 B+ 树中做一次 O(log n) 查找,定位到对应主键,再回查主对象存储获取完整对象; - 复合索引如
createIndex("by_user_time", ["userId", "timestamp"])会将两个字段拼接为联合键(如["user_123", 1625097600000]),B+ 树据此整体排序,天然支持“某用户 + 某时间段”的范围扫描; - 索引字段类型必须一致(如全为字符串或全为数字),否则 B+ 树无法比较大小,会直接抛出
DataError。
查询路径决定性能天花板
同一个查询需求,走不同路径,性能可能差 10 倍以上。关键看是否命中索引树的“有序遍历”能力:
一款AI工具,主要用于OpenClaw 确定性模型路由:支持前缀路由(`@codex` / `@mini`)、时区感知的调度切换、切换后验证、回滚以及锁保护,适合需要提升相关任务效率的用户。
-
索引 + 游标范围扫描:如用
userId索引 +IDBKeyRange.bound()查某用户全部消息,B+ 树从起始键开始顺序读取叶子节点,无需跳转,内存局部性好; -
索引 + 单点 get:适用于唯一索引(
unique: true),B+ 树直达目标叶节点,返回单个主键,再查主表 —— 这是最轻量的读操作; - 主键游标全扫:未使用任何索引时,只能打开主对象存储的游标,逐条读取所有记录再 JS 过滤,O(n) 时间 + 高内存开销;
- getAll() 后过滤:看似简洁,实则强制反序列化全部数据到内存,不仅慢,还极易触发内存抖动,10 万条消息可能吃掉数百 MB 内存。
复合索引的字段顺序不能颠倒
索引字段的声明顺序,直接决定其可支持的查询模式。以 createIndex("by_status_time", ["status", "createdAt"]) 为例:
- 能高效支持:
status === "sent"、status === "sent" && createdAt ≥ X、status === "sent" && createdAt between X and Y; - 但无法加速:
createdAt ≥ X(缺少前导字段status,B+ 树无法跳过第一层排序); - 也不等价于
["createdAt", "status"]—— 后者适合按时间查所有状态,而非按状态分组查时间。
事务边界影响查询可见性与一致性
所有查询必须在事务内执行,而事务模式决定了你能看到什么数据:
-
readonly事务:读取的是事务开始时刻的数据库快照,期间其他写事务不影响当前查询结果; -
readwrite事务:可读可写,但同一事务内多次读取同一键,结果一定一致(MVCC 保证); - 多个并发
readwrite事务对同一记录写入时,后提交者会失败(版本冲突),避免脏写; - 游标在事务中打开后,即使其他事务修改了数据,该游标仍按初始快照遍历 —— 这是“可重复读”的体现,也是分页稳定性的基础。










