Dexie.js 中索引查询的正确使用方式

在使用 Dexie.js 进行 IndexedDB 操作时，索引查询是一个常见但容易出错的功能点。许多开发者在使用 where() 方法进行范围查询时会遇到"KeyPath is not indexed"的错误提示，这通常是由于对索引创建和查询语法的误解导致的。

问题现象

当开发者尝试使用以下代码进行范围查询时：

let r = await db.tran.where(["time"]).between(2, 1000, true, true).toArray()

系统会抛出异常："KeyPath [time] on object store tran is not indexed"。

根本原因

这个错误的核心在于查询语法的不正确使用。开发者错误地在 where() 方法中使用了数组形式的参数 ["time"]，这实际上是 Dexie.js 中复合索引(compound index)的语法形式。而在这个案例中，time 只是一个简单的单字段索引，不应该使用数组语法。

正确解决方案

对于单字段索引的查询，应该直接使用字段名称作为字符串参数：

let r = await db.tran.where("time").between(2, 1000, true, true).toArray()

深入理解

1. 单字段索引 vs 复合索引

   • 单字段索引：只涉及一个字段的索引，如本例中的 "time"
   • 复合索引：涉及多个字段组合的索引，如 ["firstName", "lastName"]

2. where() 方法的正确使用

   • 对于单字段索引：直接传入字段名字符串
   • 对于复合索引：需要传入字段名数组

3. between() 方法的参数

   • 前两个参数表示范围的下限和上限
   • 后两个布尔参数分别表示是否包含下限和上限

最佳实践建议

1. 在设计数据库时明确区分单字段索引和复合索引的需求
2. 查询时根据索引类型选择正确的语法形式
3. 对于简单的单字段查询，优先考虑使用 get() 或 bulkGet() 方法
4. 范围查询时注意边界条件的处理

总结

Dexie.js 提供了强大的索引查询功能，但需要开发者正确理解和使用其语法规则。对于单字段索引的范围查询，应当避免使用数组形式的参数，直接使用字段名称字符串即可。掌握这一区别可以帮助开发者避免常见的"KeyPath is not indexed"错误，更高效地利用 IndexedDB 的查询能力。