【译】ObjectBox官方文档——查询

转载请注明出处
第一次翻译文档，水平有限，如有任何错误和不妥，望指正。此外如想知道与Realm 和 GreenDAO的对比请查看这篇博客
官网：ObjectBox
官方示例：Github

ObjectBox查询会返回符合用户定义标准的实体对象。您可以使用QueryBuilder类来指定标准并创建查询对象。查询类将在实际运行查询后返回与之匹配的对象。

QueryBuilder

QueryBuilder<T>允许您为您的实体构建自定义查询。它与实体类生成的属性类一起使用。

这个例子假定有一个实体类User及其生成的属性类User_。

  • 简单的条件示例：在所有用户中查询 first_name 为 “Joe”的用户:
    java
    1
    List<User> joes = userBox.query().equal(User_.firstName, "Joe").build().find();
  • 复杂条件示例： 查询 first_name 为“Joe”，在1970年之后出生，last_name 以 “O” 开头的用户
    java
    1
    2
    3
    4
    5
    QueryBuilder<User> builder = userBox.query();
    builder.equal(User_.firstName, "Joe")
            .greater(User_.yearOfBirth, 1970)
            .startsWith(User_.lastName, "O");
    List<User> youngJoes = builder.build().find();
    对于所有可用的标准的条件，请参考QueryBuilder类。

Query

Query是通过调用QueryBuilder的Build函数的创建：

java
1
Query<User> query = builder.build();

Finding objects

在已匹配的对象中检索有两种方法：

java
1
2
3
4
5
6
7
8
// 返回与查询匹配的所有实体
List<User> joes = query.find();
 
// 只返回第一个结果，如果没有，则返回null
User joe = query.findFirst();
 
// 找到条件匹配的唯一对象。如果没有则返回null,如果不是唯一对象，则抛出DbException
User joe = query.findUnique();

要返回匹配查询的所有实体，只需调用find()。

要返回第一个结果，使用findFirst()。

如果您希望结果是唯一的请调用 findUnique()。它会给你一个单一的结果或null，如果多个结果则会抛出异常。

复用查询对象与参数

Query对象允许多次执行查询，为了方便复用，相应的在创建Query对象时为QueryBuilder设置的参数也是可以被更改的

让我们来看看例子：

java
1
2
3
Query<User> query = userBox.query().equal(User_.firstName, "").build();
List<User> joes = query.setParameter(User_.firstName, "Joe").find();
List<User> jakes = query.setParameter(User_.firstName, "Jake").find();

这里我们使用一个查询对象来找到两组用户，每个User都有一个特定的名字。注意，在构建Query对象时，我们仍然需要初始化 firstName属性的值。如果我们总是使用.setparameter()来覆盖值，我们可以在开始构建Query`时传递 空字符串。

对于经常运行的查询，缓存查询对象是很好的做法。

分页查询

有时候，您只需要查询的一个子集，例如在用户界面中显示的前10个元素。当您拥有大量的实体，并且您不能仅使用查询条件限制结果时，这一点特别有用(并且灵活)。构建的Query<T>有一个.find(long offset, long limit)的方法，带有偏移量和限制参数:

java
1
2
Query<User> query = userBox.query().equal(UserProperties.FirstName, "Joe").build();
List<User> joes = query.find(/** offset by */ 10, /** limit to */ 5 /** results */);
  • offset:跳过第一个结果的偏移量
  • limit：查询结果的返回数限制

查询结果懒加载

为了延迟加载查询结果，Query 提供findLazy()和findLazyCached()方法，它们返回的查询结果是LazyList。

LazyList 是一个线程安全、不可修改的列表，它只在被访问时才会延迟读取实体。根据所调用的find方法，延迟列表将被 缓存 或 不缓存。缓存的列表会存储多次访问的对象，以避免多次加载实体。列表的某些功能仅限于缓存的列表(例如需要整个列表的功能)。有关更多细节，请参阅 LazyList 类文档。

映射关系的加载

关系默认是延迟加载的:当您第一次访问它时，它将执行一个数据库查找来获取数据(后续访问将读取缓存中的值)。虽然这个查找是一个使用 ObjectBox 的快速操作，如果有些情况下您想要避免它。ObjectBox 允许您立即加载关系，以完全避免这些查找。您可以使用querybuilder.eager()方法。

计量查询 Aggregates（大雾？ (￣ェ￣;) )

有时，您不希望从查询返回对象，而是获取属性的合计值。ObjectBox 支持以下方法(每个都以属性作为参数):

  • min/minDouble：找到与查询匹配的所有对象的给定属性的最小值。
  • max/maxDouble：查找最大值。
  • sum/sumDouble：计算所有值的总和。注意：non-double版本检测的溢出并在这种情况下抛出异常。(雾)
  • avg：计算所有值的平均值（始终为双倍）。

此外，您可以通过调用count()来获得结果数量，而不是自己获取结果。

删除对象

要删除匹配查询的所有对象，可以调用query.remove()。(没错，就一句话)