io.objectbox.query

Class QueryBuilder<T>

java.lang.Object

io.objectbox.query.QueryBuilder<T>

Type Parameters:

T - Entity class for which the Query is built.

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class QueryBuilder<T>
extends java.lang.Object
implements java.io.Closeable

Builds a Query using conditions which can then be used to return a list of matching Objects.

A simple example:

 userBox.query()
     .equal(User_.firstName, "Joe")
     .order(User_.lastName)
     .build()
     .find()
 

To add a condition use the appropriate method, for example equal(Property, String) or isNull(Property). To order results use order(Property) and its related methods.

Use build() to create a Query object, which is used to actually get the results.

Note: by default Query returns full Objects. To return only values or an aggregate value for a single Property, use Query.property(Property).

See the Queries documentation for details.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QueryBuilder.StringOrder

Field Summary

Fields

Modifier and Type	Field and Description
static int	CASE_SENSITIVE Makes upper case letters (e.g.
static int	DESCENDING Reverts the order from ascending (default) to descending.
static int	NULLS_LAST null values will be put last.
static int	NULLS_ZERO null values should be treated equal to zero (scalars only).
static int	UNSIGNED For scalars only: changes the comparison to unsigned (default is signed).

Constructor Summary

Constructors

Constructor and Description
QueryBuilder(Box<T> box, long storeHandle, java.lang.String entityName)

Method Summary

Modifier and Type	Method and Description
QueryBuilder<T>	and() And AND changes how conditions are combined using a following OR.
<TARGET> QueryBuilder<TARGET>	backlink(RelationInfo<TARGET,?> relationInfo) Creates a backlink (reversed link) to another entity, for which you also can describe conditions using the returned builder.
QueryBuilder<T>	between(Property<T> property, java.util.Date value1, java.util.Date value2) Finds objects with property value between and including the first and second value.
QueryBuilder<T>	between(Property<T> property, double value1, double value2) Finds objects with property value between and including the first and second value.
QueryBuilder<T>	between(Property<T> property, long value1, long value2) Finds objects with property value between and including the first and second value.
Query<T>	build() Builds the query and closes this QueryBuilder.
void	close()
QueryBuilder<T>	contains(Property<T> property, java.lang.String value) Ignores case when matching results.
QueryBuilder<T>	contains(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
QueryBuilder<T>	eager(int limit, RelationInfo relationInfo, RelationInfo... more) Like eager(RelationInfo, RelationInfo[]), but limits eager loading to the given count.
QueryBuilder<T>	eager(RelationInfo relationInfo, RelationInfo... more) Specifies relations that should be resolved eagerly.
QueryBuilder<T>	endsWith(Property<T> property, java.lang.String value) Ignores case when matching results.
QueryBuilder<T>	endsWith(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
QueryBuilder<T>	equal(Property<T> property, boolean value)
QueryBuilder<T>	equal(Property<T> property, byte[] value)
QueryBuilder<T>	equal(Property<T> property, java.util.Date value)
QueryBuilder<T>	equal(Property<T> property, double value, double tolerance) Floating point equality is non-trivial; this is just a convenience for between(Property, double, double) with parameters(property, value - tolerance, value + tolerance).
QueryBuilder<T>	equal(Property<T> property, long value)
QueryBuilder<T>	equal(Property<T> property, java.lang.String value) Creates an "equal ('=')" condition for this property.
QueryBuilder<T>	equal(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order) Creates an "equal ('=')" condition for this property.
QueryBuilder<T>	filter(QueryFilter<T> filter) Sets a filter that executes on primary query results (returned from the db core) on a Java level.
protected void	finalize() Explicitly call close() instead to avoid expensive finalization.
QueryBuilder<T>	greater(Property<T> property, byte[] value)
QueryBuilder<T>	greater(Property<T> property, java.util.Date value)
QueryBuilder<T>	greater(Property<T> property, double value)
QueryBuilder<T>	greater(Property<T> property, long value)
QueryBuilder<T>	greater(Property<T> property, java.lang.String value) Ignores case when matching results.
QueryBuilder<T>	greater(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
QueryBuilder<T>	greaterOrEqual(Property<T> property, byte[] value)
QueryBuilder<T>	greaterOrEqual(Property<T> property, java.util.Date value)
QueryBuilder<T>	greaterOrEqual(Property<T> property, double value)
QueryBuilder<T>	greaterOrEqual(Property<T> property, long value)
QueryBuilder<T>	greaterOrEqual(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
QueryBuilder<T>	in(Property<T> property, int[] values)
QueryBuilder<T>	in(Property<T> property, long[] values)
QueryBuilder<T>	in(Property<T> property, java.lang.String[] values) Ignores case when matching results.
QueryBuilder<T>	in(Property<T> property, java.lang.String[] values, QueryBuilder.StringOrder order)
QueryBuilder<T>	isNull(Property<T> property)
QueryBuilder<T>	less(Property<T> property, byte[] value)
QueryBuilder<T>	less(Property<T> property, java.util.Date value)
QueryBuilder<T>	less(Property<T> property, double value)
QueryBuilder<T>	less(Property<T> property, long value)
QueryBuilder<T>	less(Property<T> property, java.lang.String value) Ignores case when matching results.
QueryBuilder<T>	less(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
QueryBuilder<T>	lessOrEqual(Property<T> property, byte[] value)
QueryBuilder<T>	lessOrEqual(Property<T> property, java.util.Date value)
QueryBuilder<T>	lessOrEqual(Property<T> property, double value)
QueryBuilder<T>	lessOrEqual(Property<T> property, long value)
QueryBuilder<T>	lessOrEqual(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)
<TARGET> QueryBuilder<TARGET>	link(RelationInfo<?,TARGET> relationInfo) Creates a link to another entity, for which you also can describe conditions using the returned builder.
QueryBuilder<T>	notEqual(Property<T> property, boolean value)
QueryBuilder<T>	notEqual(Property<T> property, java.util.Date value)
QueryBuilder<T>	notEqual(Property<T> property, long value)
QueryBuilder<T>	notEqual(Property<T> property, java.lang.String value) Creates a "not equal ('<>')" condition for this property.
QueryBuilder<T>	notEqual(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order) Creates a "not equal ('<>')" condition for this property.
QueryBuilder<T>	notIn(Property<T> property, int[] values)
QueryBuilder<T>	notIn(Property<T> property, long[] values)
QueryBuilder<T>	notNull(Property<T> property)
QueryBuilder<T>	or() Combines the previous condition with the following condition with a logical OR.
QueryBuilder<T>	order(Property<T> property) Specifies given property to be used for sorting.
QueryBuilder<T>	order(Property<T> property, int flags) Defines the order with which the results are ordered (default: none).
QueryBuilder<T>	orderDesc(Property<T> property) Specifies given property in descending order to be used for sorting.
QueryBuilder<T>	parameterAlias(java.lang.String alias) Asigns the given alias to the previous condition.
QueryBuilder<T>	sort(java.util.Comparator<T> comparator)
QueryBuilder<T>	startsWith(Property<T> property, java.lang.String value) Ignores case when matching results.
QueryBuilder<T>	startsWith(Property<T> property, java.lang.String value, QueryBuilder.StringOrder order)

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DESCENDING

public static final int DESCENDING

Reverts the order from ascending (default) to descending.

See Also:

Constant Field Values

CASE_SENSITIVE

public static final int CASE_SENSITIVE

Makes upper case letters (e.g. "Z") be sorted before lower case letters (e.g. "a"). If not specified, the default is case insensitive for ASCII characters.

See Also:

Constant Field Values

NULLS_LAST

public static final int NULLS_LAST

null values will be put last. If not specified, by default null values will be put first.

See Also:

Constant Field Values

NULLS_ZERO

public static final int NULLS_ZERO

null values should be treated equal to zero (scalars only).

See Also:

Constant Field Values

UNSIGNED

public static final int UNSIGNED

For scalars only: changes the comparison to unsigned (default is signed).

See Also:

Constant Field Values

Constructor Detail

QueryBuilder

@Internal
public QueryBuilder(Box<T> box,
                              long storeHandle,
                              java.lang.String entityName)

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Explicitly call close() instead to avoid expensive finalization.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

close

public void close()

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

build

public Query<T> build()

Builds the query and closes this QueryBuilder.

order

public QueryBuilder<T> order(Property<T> property)

Specifies given property to be used for sorting. Shorthand for order(Property, int) with flags equal to 0.

See Also:

order(Property, int), orderDesc(Property)

orderDesc

public QueryBuilder<T> orderDesc(Property<T> property)

Specifies given property in descending order to be used for sorting. Shorthand for order(Property, int) with flags equal to DESCENDING.

See Also:

order(Property, int), order(Property)

order

public QueryBuilder<T> order(Property<T> property,
                             int flags)

Defines the order with which the results are ordered (default: none). You can chain multiple order conditions. The first applied order condition will be the most relevant. Order conditions applied afterwards are only relevant if the preceding ones resulted in value equality.

Example:

queryBuilder.order(Name).orderDesc(YearOfBirth);

Here, "Name" defines the primary sort order. The secondary sort order "YearOfBirth" is only used to compare entries with the same "Name" values.

Parameters:

property - the property defining the order

flags - Bit flags that can be combined using the binary OR operator (|). Available flags are DESCENDING, CASE_SENSITIVE, NULLS_LAST, NULLS_ZERO, and UNSIGNED.

See Also:

order(Property), orderDesc(Property)

sort

public QueryBuilder<T> sort(java.util.Comparator<T> comparator)

parameterAlias

public QueryBuilder<T> parameterAlias(java.lang.String alias)

Asigns the given alias to the previous condition.

Parameters:

alias - The string alias for use with setParameter(s) methods.

link

public <TARGET> QueryBuilder<TARGET> link(RelationInfo<?,TARGET> relationInfo)

Creates a link to another entity, for which you also can describe conditions using the returned builder.

Note: in relational databases you would use a "join" for this.

Type Parameters:

TARGET - The target entity. For parent/tree like relations, it can be the same type.

Parameters:

relationInfo - Relation meta info (generated)

Returns:

A builder to define query conditions at the target entity side.

backlink

public <TARGET> QueryBuilder<TARGET> backlink(RelationInfo<TARGET,?> relationInfo)

Creates a backlink (reversed link) to another entity, for which you also can describe conditions using the returned builder.

Note: only use this method over link(RelationInfo), if you did not define @Backlink in the entity already.

Note: in relational databases you would use a "join" for this.

Type Parameters:

TARGET - The target entity. For parent/tree like relations, it can be the same type.

Parameters:

relationInfo - Relation meta info (generated) of the original relation (reverse direction)

Returns:

A builder to define query conditions at the target entity side.

eager

public QueryBuilder<T> eager(RelationInfo relationInfo,
                             RelationInfo... more)

Specifies relations that should be resolved eagerly. This prepares the given relation objects to be preloaded (cached) avoiding further get operations from the db. A common use case is prealoading all

Parameters:

relationInfo - The relation as found in the generated meta info class ("EntityName_") of class T.

more - Supply further relations to be eagerly loaded.

eager

public QueryBuilder<T> eager(int limit,
                             RelationInfo relationInfo,
                             @Nullable
                             RelationInfo... more)

Like eager(RelationInfo, RelationInfo[]), but limits eager loading to the given count.

Parameters:

limit - Count of entities to be eager loaded.

relationInfo - The relation as found in the generated meta info class ("EntityName_") of class T.

more - Supply further relations to be eagerly loaded.

filter

public QueryBuilder<T> filter(QueryFilter<T> filter)

Sets a filter that executes on primary query results (returned from the db core) on a Java level. For efficiency reasons, you should always prefer primary criteria like equal(Property, String) if possible. A filter requires to instantiate full Java objects beforehand, which is less efficient.

The upside of filters is that they allow any complex operation including traversing object graphs, and that filtering is executed along with the query (preferably in a background thread). Use filtering wisely ;-).

Also note, that a filter may only be used along with Query.find() and Query.forEach(QueryConsumer) at this point. Other find methods will throw a exception and aggregate functions will silently ignore the filter.

or

public QueryBuilder<T> or()

Combines the previous condition with the following condition with a logical OR.

Example (querying t-shirts):

 queryBuilder.equal(color, "blue").or().less(price, 30).build() // color is blue OR price < 30
 

and

public QueryBuilder<T> and()

And AND changes how conditions are combined using a following OR. By default, all query conditions are already combined using AND. Do not use this method if all your query conditions must match (AND for all, this is the default).

However, this method change the precedence with other combinations such as or(). This is best explained by example.

Example (querying t-shirts):

 // Case (1): OR has precedence
 queryBuilder.equal(color, "blue").equal(size, "XL").or().less(price, 30).build()

 // Case (2): AND has precedence
 queryBuilder.equal(color, "blue").and().equal(size, "XL").or().less(price, 30).build()
 

Rule: Explicit AND / OR combination have precedence.

That's why (1) is evaluated like "must be blue and is either of size XL or costs less than 30", or more formally: blue AND (size XL OR price less than 30).

Rule: Conditions are applied from left to right (in the order they are called).

That's why in (2) the AND is evaluated before the OR. Thus, (2) evaluates to "either must be blue and of size XL, or costs less than 30", or, more formally: (blue AND size XL) OR price less than 30.

isNull

public QueryBuilder<T> isNull(Property<T> property)

notNull

public QueryBuilder<T> notNull(Property<T> property)

equal

public QueryBuilder<T> equal(Property<T> property,
                             long value)

notEqual

public QueryBuilder<T> notEqual(Property<T> property,
                                long value)

less

public QueryBuilder<T> less(Property<T> property,
                            long value)

lessOrEqual

public QueryBuilder<T> lessOrEqual(Property<T> property,
                                   long value)

greater

public QueryBuilder<T> greater(Property<T> property,
                               long value)

greaterOrEqual

public QueryBuilder<T> greaterOrEqual(Property<T> property,
                                      long value)

between

public QueryBuilder<T> between(Property<T> property,
                               long value1,
                               long value2)

Finds objects with property value between and including the first and second value.

in

public QueryBuilder<T> in(Property<T> property,
                          long[] values)

notIn

public QueryBuilder<T> notIn(Property<T> property,
                             long[] values)

in

public QueryBuilder<T> in(Property<T> property,
                          int[] values)

notIn

public QueryBuilder<T> notIn(Property<T> property,
                             int[] values)

equal

public QueryBuilder<T> equal(Property<T> property,
                             boolean value)

notEqual

public QueryBuilder<T> notEqual(Property<T> property,
                                boolean value)

equal

public QueryBuilder<T> equal(Property<T> property,
                             java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

notEqual

public QueryBuilder<T> notEqual(Property<T> property,
                                java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

less

public QueryBuilder<T> less(Property<T> property,
                            java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

lessOrEqual

public QueryBuilder<T> lessOrEqual(Property<T> property,
                                   java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

greater

public QueryBuilder<T> greater(Property<T> property,
                               java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

greaterOrEqual

public QueryBuilder<T> greaterOrEqual(Property<T> property,
                                      java.util.Date value)

Throws:

java.lang.NullPointerException - if given value is null. Use isNull(Property) instead.

between

public QueryBuilder<T> between(Property<T> property,
                               java.util.Date value1,
                               java.util.Date value2)

Finds objects with property value between and including the first and second value.

Throws:

java.lang.NullPointerException - if one of the given values is null.

equal

public QueryBuilder<T> equal(Property<T> property,
                             java.lang.String value)

Creates an "equal ('=')" condition for this property.

Ignores case when matching results, e.g. equal(prop, "example") matches both "Example" and "example".

Use equal(prop, value, StringOrder.CASE_SENSITIVE) to only match if case is equal.

Note: Use a case sensitive condition to utilize an @Index on property, dramatically speeding up look-up of results.

equal

public QueryBuilder<T> equal(Property<T> property,
                             java.lang.String value,
                             QueryBuilder.StringOrder order)

Creates an "equal ('=')" condition for this property.

Set order to StringOrder.CASE_SENSITIVE to only match if case is equal. E.g. equal(prop, "example", StringOrder.CASE_SENSITIVE) only matches "example", but not "Example".

Note: Use a case sensitive condition to utilize an @Index on property, dramatically speeding up look-up of results.

notEqual

public QueryBuilder<T> notEqual(Property<T> property,
                                java.lang.String value)

Creates a "not equal ('<>')" condition for this property.

Ignores case when matching results, e.g. notEqual(prop, "example") excludes both "Example" and "example".

Use notEqual(prop, value, StringOrder.CASE_SENSITIVE) to only exclude if case is equal.

Note: Use a case sensitive condition to utilize an @Index on property, dramatically speeding up look-up of results.

notEqual

public QueryBuilder<T> notEqual(Property<T> property,
                                java.lang.String value,
                                QueryBuilder.StringOrder order)

Creates a "not equal ('<>')" condition for this property.

Set order to StringOrder.CASE_SENSITIVE to only exclude if case is equal. E.g. notEqual(prop, "example", StringOrder.CASE_SENSITIVE) only excludes "example", but not "Example".

Note: Use a case sensitive condition to utilize an @Index on property, dramatically speeding up look-up of results.

contains

public QueryBuilder<T> contains(Property<T> property,
                                java.lang.String value)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

startsWith

public QueryBuilder<T> startsWith(Property<T> property,
                                  java.lang.String value)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

endsWith

public QueryBuilder<T> endsWith(Property<T> property,
                                java.lang.String value)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

contains

public QueryBuilder<T> contains(Property<T> property,
                                java.lang.String value,
                                QueryBuilder.StringOrder order)

startsWith

public QueryBuilder<T> startsWith(Property<T> property,
                                  java.lang.String value,
                                  QueryBuilder.StringOrder order)

endsWith

public QueryBuilder<T> endsWith(Property<T> property,
                                java.lang.String value,
                                QueryBuilder.StringOrder order)

less

public QueryBuilder<T> less(Property<T> property,
                            java.lang.String value)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

less

public QueryBuilder<T> less(Property<T> property,
                            java.lang.String value,
                            QueryBuilder.StringOrder order)

lessOrEqual

public QueryBuilder<T> lessOrEqual(Property<T> property,
                                   java.lang.String value,
                                   QueryBuilder.StringOrder order)

greater

public QueryBuilder<T> greater(Property<T> property,
                               java.lang.String value)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

greater

public QueryBuilder<T> greater(Property<T> property,
                               java.lang.String value,
                               QueryBuilder.StringOrder order)

greaterOrEqual

public QueryBuilder<T> greaterOrEqual(Property<T> property,
                                      java.lang.String value,
                                      QueryBuilder.StringOrder order)

in

public QueryBuilder<T> in(Property<T> property,
                          java.lang.String[] values)

Ignores case when matching results. Use the overload and pass StringOrder.CASE_SENSITIVE to specify that case should not be ignored.

in

public QueryBuilder<T> in(Property<T> property,
                          java.lang.String[] values,
                          QueryBuilder.StringOrder order)

equal

public QueryBuilder<T> equal(Property<T> property,
                             double value,
                             double tolerance)

Floating point equality is non-trivial; this is just a convenience for between(Property, double, double) with parameters(property, value - tolerance, value + tolerance). When using Query.setParameters(Property, double, double), consider that the params are the lower and upper bounds.

less

public QueryBuilder<T> less(Property<T> property,
                            double value)

lessOrEqual

public QueryBuilder<T> lessOrEqual(Property<T> property,
                                   double value)

greater

public QueryBuilder<T> greater(Property<T> property,
                               double value)

greaterOrEqual

public QueryBuilder<T> greaterOrEqual(Property<T> property,
                                      double value)

between

public QueryBuilder<T> between(Property<T> property,
                               double value1,
                               double value2)

Finds objects with property value between and including the first and second value.

equal

public QueryBuilder<T> equal(Property<T> property,
                             byte[] value)

less

public QueryBuilder<T> less(Property<T> property,
                            byte[] value)

lessOrEqual

public QueryBuilder<T> lessOrEqual(Property<T> property,
                                   byte[] value)

greater

public QueryBuilder<T> greater(Property<T> property,
                               byte[] value)

greaterOrEqual

public QueryBuilder<T> greaterOrEqual(Property<T> property,
                                      byte[] value)