Class QueryBuilder<T>

  • Type Parameters:
    T - Entity class associated with this query builder.
    All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

    @Experimental
    public class QueryBuilder<T>
    extends java.lang.Object
    implements java.io.Closeable
    With QueryBuilder you define custom queries returning matching entities. Using the methods of this class you can select (filter) results for specific data (for example #equal(Property, String) and isNull(Property)) and select an sort order for the resulting list (see order(Property) and its overloads).

    Use build() to conclude your query definitions and to get a Query object, which is used to actually get results.

    Note: Currently you can only query for complete entities. Returning individual property values or aggregates are currently not available. Keep in mind that ObjectBox is very fast and the overhead to create an entity is very low.

    • 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.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
      • build

        public Query<T> build()
        Builds the query and closes this QueryBuilder.
      • 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.

      • between

        public QueryBuilder<T> between​(Property<T> property,
                                       java.util.Date value1,
                                       java.util.Date value2)
        Throws:
        java.lang.NullPointerException - if one of the given values is null.