ObjectBox Queries

Queries return persisted objects that match user defined criteria. In ObjectBox, you use the QueryBuilder class to specify criteria and create Query objects. The Query class will actually run the query and return matching objects.

QueryBuilder

The QueryBuilder<T> class together with the properties class generated for each entity lets you build custom queries for your entities.

This example assumes an entity class User and its generated class User_.

Simple condition example: Query for all users with the first name “Joe”:

Multiple conditions example: Get users with the first name “Joe” that are born later than 1970 and whose last name starts with “O”.

For an overview of all available criteria, please refer to the QueryBuilder class. We will extend the documentation here soon.

Query

Queries are created (and not yet executed) by calling build() on the QueryBuilder.

Finding objects

There are a couple of find methods to retrieve objects matching the query:

To return all entities matching the query simply call find().

To only return the first result, use findFirst().

If you expect a unique result call findUnique() instead. It will give you a single result or null, if no matching entity was found and throw an exception if there was more than one result.

Reusing Queries and Parameters

Query objects allow to execute queries multiple times in an efficient way. To make queries more reusable all criteria values you previously set in the QueryBuilder can be changed. That’s why we call them query parameters.

Let’s look at example:

Here we used one query object to find two sets of users, each with a specific first name. Note that we still have to initialize the value for the firstName property when building the query. Because we always overwrite the value using .setParameter() , we can just pass an empty string.

Caching the query object is good practice for queries that run frequently.

Limit, Offset, and Pagination

Sometimes you only need a subset of a query, for example the first 10 elements to display in your user interface. This is especially helpful (and resourceful) when you have a high number of entities and you cannot limit the result using query conditions only. The built Query<T> has a .find(int offset, int limit) method with offset and limit arguments:

offset: The first offset results are skipped.

limit: At most limit results of this query are returned.

Aggregates

Sometimes you do not want to return objects from a query, but get an aggregated value of a property. ObjectBox supports the following methods (each taking a property as parameter):

  • min / minDouble: the minimum value
  • max / maxDouble: the maximum value
  • sum / sumDouble : the sum of all values – note that the non-double version detects overflows and throws an exception in that case
  • avg : the average (always a double)

Removing Objects

To remove all objects matching a query, call query.remove() .

Spread the love
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •