Package 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.
public class QueryBuilder<T> extends Object
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", 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.

  • Field Details

    • DESCENDING

      public static final int DESCENDING
      Reverts the order from ascending (default) to descending.
      See Also:

    • 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:

    • 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:

    • NULLS_ZERO

      public static final int NULLS_ZERO
      null values should be treated equal to zero (scalars only).
      See Also:

    • UNSIGNED

      public static final int UNSIGNED
      For scalars only: changes the comparison to unsigned (default is signed).
      See Also:

    • box

      private final Box<T> box

    • storeHandle

      private final long storeHandle

    • handle

      private long handle

    • lastCondition

      private long lastCondition
      Holds on to last condition. May be a property condition or a combined condition.

    • lastPropertyCondition

      private long lastPropertyCondition
      Holds on to last property condition to use with parameterAlias(String)

    • combineNextWith

      private QueryBuilder.Operator combineNextWith

    • eagerRelations

      @Nullable private List<EagerRelation<T,?>> eagerRelations

    • filter

      @Nullable private QueryFilter<T> filter

    • comparator

      @Nullable private Comparator<T> comparator

    • isSubQuery

      private final boolean isSubQuery

  • Constructor Details

    • QueryBuilder

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

    • QueryBuilder

      private QueryBuilder(long storeHandle, long subQueryBuilderHandle)

  • Method Details

    • nativeCreate

      private long nativeCreate(long storeHandle, String entityName)

    • nativeDestroy

      private void nativeDestroy(long handle)

    • nativeBuild

      private long nativeBuild(long handle)

    • nativeLink

      private long nativeLink(long handle, long storeHandle, int relationOwnerEntityId, int targetEntityId, int propertyId, int relationId, boolean backlink)

    • nativeOrder

      private void nativeOrder(long handle, int propertyId, int flags)

    • nativeCombine

      private long nativeCombine(long handle, long condition1, long condition2, boolean combineUsingOr)

    • nativeSetParameterAlias

      private void nativeSetParameterAlias(long conditionHandle, String alias)

    • nativeRelationCount

      private long nativeRelationCount(long handle, long storeHandle, int relationOwnerEntityId, int propertyId, int relationCount)

    • nativeNull

      private long nativeNull(long handle, int propertyId)

    • nativeNotNull

      private long nativeNotNull(long handle, int propertyId)

    • nativeEqual

      private long nativeEqual(long handle, int propertyId, long value)

    • nativeNotEqual

      private long nativeNotEqual(long handle, int propertyId, long value)

    • nativeLess

      private long nativeLess(long handle, int propertyId, long value, boolean withEqual)

    • nativeGreater

      private long nativeGreater(long handle, int propertyId, long value, boolean withEqual)

    • nativeBetween

      private long nativeBetween(long handle, int propertyId, long value1, long value2)

    • nativeIn

      private long nativeIn(long handle, int propertyId, int[] values, boolean negate)

    • nativeIn

      private long nativeIn(long handle, int propertyId, long[] values, boolean negate)

    • nativeEqual

      private long nativeEqual(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeNotEqual

      private long nativeNotEqual(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeContains

      private long nativeContains(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeContainsElement

      private long nativeContainsElement(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeContainsKeyValue

      private long nativeContainsKeyValue(long handle, int propertyId, String key, String value, boolean caseSensitive)

    • nativeStartsWith

      private long nativeStartsWith(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeEndsWith

      private long nativeEndsWith(long handle, int propertyId, String value, boolean caseSensitive)

    • nativeLess

      private long nativeLess(long handle, int propertyId, String value, boolean caseSensitive, boolean withEqual)

    • nativeGreater

      private long nativeGreater(long handle, int propertyId, String value, boolean caseSensitive, boolean withEqual)

    • nativeIn

      private long nativeIn(long handle, int propertyId, String[] value, boolean caseSensitive)

    • nativeLess

      private long nativeLess(long handle, int propertyId, double value, boolean withEqual)

    • nativeGreater

      private long nativeGreater(long handle, int propertyId, double value, boolean withEqual)

    • nativeBetween

      private long nativeBetween(long handle, int propertyId, double value1, double value2)

    • nativeNearestNeighborsF32

      private long nativeNearestNeighborsF32(long handle, int propertyId, float[] queryVector, int maxResultCount)

    • nativeEqual

      private long nativeEqual(long handle, int propertyId, byte[] value)

    • nativeLess

      private long nativeLess(long handle, int propertyId, byte[] value, boolean withEqual)

    • nativeGreater

      private long nativeGreater(long handle, int propertyId, byte[] value, boolean withEqual)

    • finalize

      protected void finalize() throws Throwable
      Typically build() is called on this which calls close() and avoids expensive finalization here.

      If build() is not called, make sure to explicitly call close().

      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • close

      public void close()
      Close this query builder and free used resources.

      This is not required when calling build().

    • build

      public Query<T> build()
      Builds the query and closes this QueryBuilder.

    • verifyNotSubQuery

      private void verifyNotSubQuery()

    • verifyHandle

      private void verifyHandle()

    • apply

      public QueryBuilder<T> apply(QueryCondition<T> queryCondition)
      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")))
      Use Box.query(QueryCondition) as a shortcut for this method.

    • 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:

    • 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

      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:

    • sort

      public QueryBuilder<T> sort(Comparator<T> comparator)

    • parameterAlias

      public QueryBuilder<T> parameterAlias(String alias)
      Note: New code should use the new 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

      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.

    • link

      private <TARGET> QueryBuilder<TARGET> link(RelationInfo<?,?> relationInfo, EntityInfo<?> relationOwner, EntityInfo<?> target, boolean backlink)

    • 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 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

      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, 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() 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.

    • combineOperator

      private void combineOperator(QueryBuilder.Operator operator)

    • checkNoOperatorPending

      private void checkNoOperatorPending()

    • checkCombineCondition

      private void checkCombineCondition(long currentCondition)

    • internalGetLastCondition

      @Internal long internalGetLastCondition()

    • internalAnd

      @Internal void internalAnd(long leftCondition, long rightCondition)

    • internalOr

      @Internal void internalOr(long leftCondition, long rightCondition)

    • isNull

      public QueryBuilder<T> isNull(Property<T> property)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • notNull

      public QueryBuilder<T> notNull(Property<T> property)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • relationCount

      public QueryBuilder<T> relationCount(RelationInfo<T,?> relationInfo, int relationCount)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • equal

      public QueryBuilder<T> equal(Property<T> property, long value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • notEqual

      public QueryBuilder<T> notEqual(Property<T> property, long value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • less

      public QueryBuilder<T> less(Property<T> property, long value)
      Note: New code should use the new 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, long value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • greater

      public QueryBuilder<T> greater(Property<T> property, long value)
      Note: New code should use the new 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, long value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • between

      public QueryBuilder<T> between(Property<T> property, long value1, long value2)
      Note: New code should use the new 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

      public QueryBuilder<T> in(Property<T> property, long[] values)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • notIn

      public QueryBuilder<T> notIn(Property<T> property, long[] values)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • in

      public QueryBuilder<T> in(Property<T> property, int[] values)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • notIn

      public QueryBuilder<T> notIn(Property<T> property, int[] values)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • equal

      public QueryBuilder<T> equal(Property<T> property, boolean value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • notEqual

      public QueryBuilder<T> notEqual(Property<T> property, boolean value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • equal

      public QueryBuilder<T> equal(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • notEqual

      public QueryBuilder<T> notEqual(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • less

      public QueryBuilder<T> less(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • lessOrEqual

      public QueryBuilder<T> lessOrEqual(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • greater

      public QueryBuilder<T> greater(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • greaterOrEqual

      public QueryBuilder<T> greaterOrEqual(Property<T> property, Date value)
      Note: New code should use the new 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. Use isNull(Property) instead.

    • between

      public QueryBuilder<T> between(Property<T> property, Date value1, Date value2)
      Note: New code should use the new 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

      public QueryBuilder<T> equal(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new 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

      public QueryBuilder<T> notEqual(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new 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

      public QueryBuilder<T> contains(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new 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 the new 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

      public QueryBuilder<T> containsKeyValue(Property<T> property, String key, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

      For a String-key map property, matches if at least one key and value combination equals the given values.

    • startsWith

      public QueryBuilder<T> startsWith(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • endsWith

      public QueryBuilder<T> endsWith(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • less

      public QueryBuilder<T> less(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new 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 the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • greater

      public QueryBuilder<T> greater(Property<T> property, String value, QueryBuilder.StringOrder order)
      Note: New code should use the new 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 the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • in

      public QueryBuilder<T> in(Property<T> property, String[] values, QueryBuilder.StringOrder order)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • equal

      public QueryBuilder<T> equal(Property<T> property, double value, double tolerance)
      Note: New code should use the new 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 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)
      Note: New code should use the new 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, double value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • greater

      public QueryBuilder<T> greater(Property<T> property, double value)
      Note: New code should use the new 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, double value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • between

      public QueryBuilder<T> between(Property<T> property, double value1, double value2)
      Note: New code should use the new 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 the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • equal

      public QueryBuilder<T> equal(Property<T> property, byte[] value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • less

      public QueryBuilder<T> less(Property<T> property, byte[] value)
      Note: New code should use the new 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, byte[] value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.

    • greater

      public QueryBuilder<T> greater(Property<T> property, byte[] value)
      Note: New code should use the new 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, byte[] value)
      Note: New code should use the new query API. Existing code can continue to use this, there are currently no plans to remove the old query API.