QueryBuilder<T>class lets you build custom queries for your entities. Create an instance via
QueryBuilderoffers several methods to define query conditions for properties of an entity. To specify a property ObjectBox does not use their names as text but meta-information "underscore" classes (like
User_) that are generated during build time. The meta-information classes have a static field for each property (like
User_.firstName). This allows referencing properties safely with compile-time checks to prevent runtime errors, for example, because of typos.
3.0.0introduces a new query API that accepts complex nested conditions, e.g. the equivalent of
(A or B) and (C or D).
Box.query(condition)and supply a
conditionbuilt using entity
property.equal(value). All properties of an entity can be accessed using its underscore class. For example, for an entity
conditionusing it could be
QueryCondition.or(condition). This implicitly adds parentheses around the combined conditions, e.g.
cond1.and(cond2)is logically equivalent to
(cond1 AND cond2).
inValues(property, array)for Kotlin) condition.
condition and conditionand
condition or condition.
condition & conditionand
condition | conditon
condition.alias(aliasName)to set an alias for a
conditionthat can later be used with the
less()there are also conditions like:
between()to filter for values that are between the given two,
notIn()to filter for values that match any in the given array,
contains()for extended String filtering.
or()to build more complex combinations of conditions.
order()to sort in descending order, to sort case sensitive or to specially treat null values. For example to sort the above results in descending order and case sensitive instead:
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.
Queryobject and re-use it. To make a
Querymore reusable you can change the values, or query parameters, of each condition you added even after the
Queryis built. Let's see how.
firstNamevalues. First, we build a regular
firstName. Because we have to pass an initial parameter value to
equal()but plan to override it before running the
Querylater, we just pass an empty string:
Querywith an actual value for the
firstName? For this purpose you can assign each parameter an alias while specifying the condition:
offsetresults are skipped.
limitresults are returned.
findLazyCached()which return a
LazyListof the query results.
find()you can stream it using
property(Property)to define the property followed by the appropriate find method.
Users, to just get their email addresses:
minDouble(): Finds the minimum value for the given property over all objects matching the query.
maxDouble(): Finds the maximum value.
sumDouble(): Calculates the sum of all values. Note: the non-double version detects overflows and throws an exception in that case.
avg(): Calculates the average (always a double) of all values.
count(): returns the number of results. This is faster than finding and getting the length of the result array. Can be combined with
distinct()to count only the number of distinct values.
Personthat can be associated with multiple
Personwith a certain name that also lives on a specific street, we need to query the associated
Addressentities of a
Person. To do this, use the
link()method of the query builder to tell that the
addressesrelation should be queried. Then add a condition for
Person? If you know ObjectBox relations well, you would probably add a
Addressand build your query using it with
link()as shown above:
Addressentity (you still can if you need the
@Backlinkelsewhere). Instead, we can use the
backlink()method to create a backlink to the
Personjust for that query:
ToManyproperty it will perform a database lookup to get its data. On each subsequent access it will use a cached version of that data.
ToManyvalues before the query results are returned. To do this call the
QueryBuilder.eagermethod when building your query and pass the
RelationInfoobjects associated with the
ToManyproperties to prefetch: