Class QueryBuilder<T>
- Type Parameters:
T
- Entity class for which the Query is built.
Query
using conditions which can then be used to return a list of matching Objects.
A simple example:
userBox.query() .equal(User_.firstName, "Joe", StringOrder.CASE_SENSITIVE) .order(User_.lastName) .build() .find()
To add a condition use the appropriate method, for example equal(Property, String, StringOrder)
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 -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Makes upper case letters (e.g.static final int
Reverts the order from ascending (default) to descending.static final int
null values will be put last.static final int
null values should be treated equal to zero (scalars only).static final int
For scalars only: changes the comparison to unsigned (default is signed). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionand()
And AND changes how conditions are combined using a following OR.apply
(QueryCondition<T> queryCondition) Applies the given query conditions and returns the builder for further customization, such as result order.<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: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.build()
Builds the query and closes this QueryBuilder.void
close()
Close this query builder and free used resources.contains
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.containsElement
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.containsKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Deprecated.eager
(int limit, RelationInfo relationInfo, RelationInfo... more) Likeeager(RelationInfo, RelationInfo[])
, but limits eager loading to the given count.eager
(RelationInfo relationInfo, RelationInfo... more) Specifies relations that should be resolved eagerly.endsWith
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.equal
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.equalKeyValue
(Property<T> property, String key, double value) Note: UseProperty.equalKeyValue(String, double)
with thenew query API
instead.equalKeyValue
(Property<T> property, String key, long value) Note: UseProperty.equalKeyValue(String, long)
with thenew query API
instead.equalKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.equalKeyValue(String, String, StringOrder)
with thenew query API
instead.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()
Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.greater
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.greaterKeyValue
(Property<T> property, String key, double value) Note: UseProperty.greaterKeyValue(String, double)
with thenew query API
instead.greaterKeyValue
(Property<T> property, String key, long value) Note: UseProperty.greaterOrEqualKeyValue(String, long)
(String, String, StringOrder)} with thenew query API
instead.greaterKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.greaterKeyValue(String, String, StringOrder)
with thenew query API
instead.greaterOrEqual
(Property<T> property, byte[] value) Note: New code should use thenew query API
.greaterOrEqual
(Property<T> property, double value) Note: New code should use thenew query API
.greaterOrEqual
(Property<T> property, long value) Note: New code should use thenew query API
.greaterOrEqual
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.greaterOrEqual
(Property<T> property, Date value) Note: New code should use thenew query API
.greaterOrEqualKeyValue
(Property<T> property, String key, double value) Note: UseProperty.greaterOrEqualKeyValue(String, double)
with thenew query API
instead.greaterOrEqualKeyValue
(Property<T> property, String key, long value) Note: UseProperty.greaterOrEqualKeyValue(String, long)
with thenew query API
instead.greaterOrEqualKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.greaterOrEqualKeyValue(String, String, StringOrder)
with thenew query API
instead.Note: New code should use thenew query API
.Note: New code should use thenew query API
.in
(Property<T> property, String[] values, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.less
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.lessKeyValue
(Property<T> property, String key, double value) Note: UseProperty.lessKeyValue(String, double)
with thenew query API
instead.lessKeyValue
(Property<T> property, String key, long value) Note: UseProperty.lessKeyValue(String, long)
with thenew query API
instead.lessKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.lessKeyValue(String, String, StringOrder)
with thenew query API
instead.lessOrEqual
(Property<T> property, byte[] value) Note: New code should use thenew query API
.lessOrEqual
(Property<T> property, double value) Note: New code should use thenew query API
.lessOrEqual
(Property<T> property, long value) Note: New code should use thenew query API
.lessOrEqual
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.lessOrEqual
(Property<T> property, Date value) Note: New code should use thenew query API
.lessOrEqualKeyValue
(Property<T> property, String key, double value) Note: UseProperty.lessOrEqualKeyValue(String, double)
with thenew query API
instead.lessOrEqualKeyValue
(Property<T> property, String key, long value) Note: UseProperty.lessOrEqualKeyValue(String, long)
with thenew query API
instead.lessOrEqualKeyValue
(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.lessOrEqualKeyValue(String, String, StringOrder)
with thenew query API
instead.<TARGET> QueryBuilder<TARGET>
link
(RelationInfo<?, TARGET> relationInfo) Creates a link to another entity, for which you also can describe conditions using the returned builder.nearestNeighbors
(Property<T> property, float[] queryVector, int maxResultCount) Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.notEqual
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.Note: New code should use thenew query API
.or()
Combines the previous condition with the following condition with a logical OR.Specifies given property to be used for sorting.Defines the order with which the results are ordered (default: none).Specifies given property in descending order to be used for sorting.parameterAlias
(String alias) Note: New code should use thenew query API
.relationCount
(RelationInfo<T, ?> relationInfo, int relationCount) Note: New code should use thenew query API
.sort
(Comparator<T> comparator) startsWith
(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
.
-
Field Details
-
DESCENDING
public static final int DESCENDINGReverts the order from ascending (default) to descending.- See Also:
-
CASE_SENSITIVE
public static final int CASE_SENSITIVEMakes 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:
-
NULLS_LAST
public static final int NULLS_LASTnull values will be put last. If not specified, by default null values will be put first.- See Also:
-
NULLS_ZERO
public static final int NULLS_ZEROnull values should be treated equal to zero (scalars only).- See Also:
-
UNSIGNED
public static final int UNSIGNEDFor scalars only: changes the comparison to unsigned (default is signed).- See Also:
-
-
Constructor Details
-
QueryBuilder
-
-
Method Details
-
finalize
-
close
public void close()Close this query builder and free used resources.This is not required when calling
build()
. -
build
Builds the query and closes this QueryBuilder. -
apply
Applies the given query conditions and returns the builder for further customization, such as result order. Build the condition using the properties from your entity underscore classes.An example with a nested OR condition:
# Java builder.apply(User_.name.equal("Jane") .and(User_.age.less(12) .or(User_.status.equal("child")))); # Kotlin builder.apply(User_.name.equal("Jane") and (User_.age.less(12) or User_.status.equal("child")))
UseBox.query(QueryCondition)
as a shortcut for this method. -
order
Specifies given property to be used for sorting. Shorthand fororder(Property, int)
with flags equal to 0.- See Also:
-
orderDesc
Specifies given property in descending order to be used for sorting. Shorthand fororder(Property, int)
with flags equal toDESCENDING
.- See Also:
-
order
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 orderflags
- Bit flags that can be combined using the binary OR operator (|). Available flags areDESCENDING
,CASE_SENSITIVE
,NULLS_LAST
,NULLS_ZERO
, andUNSIGNED
.- See Also:
-
sort
-
parameterAlias
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Assigns the given alias to the previous condition.
- Parameters:
alias
- The string alias for use with setParameter(s) methods.
-
link
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
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
Specifies relations that should be resolved eagerly. This prepares the given relation objects to be preloaded (cached) avoiding further get operations from the database.- 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
Likeeager(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
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 likeequal(Property, long)
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()
andQuery.forEach(QueryConsumer)
at this point. Other find methods will throw a exception and aggregate functions will silently ignore the filter. -
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
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
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
notNull
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
relationCount
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
notEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
less
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
lessOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greater
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greaterOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
between
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Finds objects with property value between and including the first and second value.
-
in
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
notIn
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
in
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
notIn
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
notEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
notEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
less
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
lessOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
greater
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
greaterOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.- Throws:
NullPointerException
- if given value is null. UseisNull(Property)
instead.
-
between
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Finds objects with property value between and including the first and second value.
- Throws:
NullPointerException
- if one of the given values is null.
-
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Creates an "equal ('=')" condition for this property.
-
notEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Creates a "not equal ('<>')" condition for this property.
-
contains
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Creates a contains condition.
Note: for a String array property, use
containsElement(io.objectbox.Property<T>, java.lang.String, io.objectbox.query.QueryBuilder.StringOrder)
instead. -
containsElement
public QueryBuilder<T> containsElement(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.For a String array, list or String-key map property, matches if at least one element equals the given value.
-
containsKeyValue
@Deprecated public QueryBuilder<T> containsKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Deprecated.UseProperty.equalKeyValue(String, String, StringOrder)
with thenew query API
instead. -
equalKeyValue
public QueryBuilder<T> equalKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.equalKeyValue(String, String, StringOrder)
with thenew query API
instead. -
lessKeyValue
public QueryBuilder<T> lessKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.lessKeyValue(String, String, StringOrder)
with thenew query API
instead. -
lessOrEqualKeyValue
public QueryBuilder<T> lessOrEqualKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.lessOrEqualKeyValue(String, String, StringOrder)
with thenew query API
instead. -
greaterKeyValue
public QueryBuilder<T> greaterKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.greaterKeyValue(String, String, StringOrder)
with thenew query API
instead. -
greaterOrEqualKeyValue
public QueryBuilder<T> greaterOrEqualKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order) Note: UseProperty.greaterOrEqualKeyValue(String, String, StringOrder)
with thenew query API
instead. -
equalKeyValue
Note: UseProperty.equalKeyValue(String, long)
with thenew query API
instead. -
lessKeyValue
Note: UseProperty.lessKeyValue(String, long)
with thenew query API
instead. -
lessOrEqualKeyValue
Note: UseProperty.lessOrEqualKeyValue(String, long)
with thenew query API
instead. -
greaterKeyValue
Note: UseProperty.greaterOrEqualKeyValue(String, long)
(String, String, StringOrder)} with thenew query API
instead. -
greaterOrEqualKeyValue
Note: UseProperty.greaterOrEqualKeyValue(String, long)
with thenew query API
instead. -
equalKeyValue
Note: UseProperty.equalKeyValue(String, double)
with thenew query API
instead. -
lessKeyValue
Note: UseProperty.lessKeyValue(String, double)
with thenew query API
instead. -
lessOrEqualKeyValue
Note: UseProperty.lessOrEqualKeyValue(String, double)
with thenew query API
instead. -
greaterKeyValue
Note: UseProperty.greaterKeyValue(String, double)
with thenew query API
instead. -
greaterOrEqualKeyValue
Note: UseProperty.greaterOrEqualKeyValue(String, double)
with thenew query API
instead. -
startsWith
public QueryBuilder<T> startsWith(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
endsWith
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
less
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
lessOrEqual
public QueryBuilder<T> lessOrEqual(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greater
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greaterOrEqual
public QueryBuilder<T> greaterOrEqual(Property<T> property, String value, QueryBuilder.StringOrder order) Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
in
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Floating point equality is non-trivial; this is just a convenience for
between(Property, double, double)
with parameters(property, value - tolerance, value + tolerance). When usingQuery.setParameters(Property, double, double)
, consider that the params are the lower and upper bounds. -
less
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
lessOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greater
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greaterOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
between
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.Finds objects with property value between and including the first and second value.
-
nearestNeighbors
public QueryBuilder<T> nearestNeighbors(Property<T> property, float[] queryVector, int maxResultCount) Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
equal
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
less
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
lessOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greater
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API. -
greaterOrEqual
Note: New code should use thenew query API
. Existing code can continue to use this, there are currently no plans to remove the old query API.
-
Property.equalKeyValue(String, String, StringOrder)
with thenew query API
instead.