Package io.objectbox.query

Class Query<T>

java.lang.Object
io.objectbox.query.Query<T>
Type Parameters:
T - Entity class for which results are returned.
All Implemented Interfaces:
Closeable, AutoCloseable
public class Query<T> extends Object implements Closeable
A repeatable Query returning the latest matching objects.

Use find() or related methods to fetch the latest results from the BoxStore.

Use property(Property) to only return values or an aggregate of a single Property.

Make sure to close() this query once done with it to reclaim resources immediately.

See the Queries documentation for details.

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Explicitly call close() instead to avoid expensive finalization.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • close

      public void close()
      Closes this query and frees used resources.

      If possible, call this always once done with this. Otherwise, will be called once this is finalized (e.g. garbage collected).

      Calling any other methods of this afterwards will throw an IllegalStateException.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • copy

      public Query<T> copy()
      Creates a copy of this for use in another thread.

      Clones the native query, keeping any previously set parameters.

      Closing the original query does not close the copy. close() the copy once finished using it.

      Note: a set filter or sort order must be thread safe.

    • findFirst

      @Nullable public T findFirst()
      Finds the first object matching this query.

      Note: if no QueryBuilder.order(io.objectbox.Property<T>) conditions are present, which object is the first one might be arbitrary (sometimes the one with the lowest ID, but never guaranteed to be).

      Returns:
      The first object if there are matches. null if no object matches.

    • findUnique

      @Nullable public T findUnique()
      Finds the only object matching this query.
      Returns:
      The object if a single object matches. null if no object matches. Throws NonUniqueResultException if there are multiple objects matching the query.

    • find

      @Nonnull public List<T> find()
      Finds objects matching the query.

      Note: if no QueryBuilder.order(io.objectbox.Property<T>) conditions are present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).

      Returns:
      A list of matching objects. An empty list if no object matches.

    • find

      @Nonnull public List<T> find(long offset, long limit)
      Like find(), but can skip and limit results.

      Use to get a slice of the whole result, e.g. for "result paging".

      Parameters:
      offset - If greater than 0, skips this many results.
      limit - If greater than 0, returns at most this many results.

    • findFirstId

      public long findFirstId()
      Like findFirst(), but returns just the ID of the object.

      This is more efficient as no object is created.

      Ignores any query filter.

      Returns:
      The ID of the first matching object. 0 if no object matches.

    • findUniqueId

      public long findUniqueId()
      Like findUnique(), but returns just the ID of the object.

      This is more efficient as no object is created.

      Ignores any query filter.

      Returns:
      The ID of the object, if a single object matches. 0 if no object matches. Throws NonUniqueResultException if there are multiple objects matching the query.

    • findIds

      @Nonnull public long[] findIds()
      Like find(), but returns just the IDs of the objects.

      IDs can later be used to Box.get(long) objects.

      This is very efficient as no objects are created.

      Note: a filter set with QueryBuilder.filter(QueryFilter) will be silently ignored!

      Returns:
      An array of IDs of matching objects. An empty array if no objects match.

    • findIds

      @Nonnull public long[] findIds(long offset, long limit)
      Like findIds(), but can skip and limit results.

      Use to get a slice of the whole result, e.g. for "result paging".

      Note: a filter set with QueryBuilder.filter(QueryFilter) will be silently ignored!

      Parameters:
      offset - If greater than 0, skips this many results.
      limit - If greater than 0, returns at most this many results.

    • findLazy

      @Nonnull public LazyList<T> findLazy()
      Like findIds(), but wraps the Object IDs in an unmodifiable LazyList so Objects can be retrieved on demand. The LazyList does not cache retrieved Objects, so only basic List operations like getting or iterating list items are supported. See LazyList for details.

    • findLazyCached

      @Nonnull public LazyList<T> findLazyCached()
      Like findIds(), but wraps the Object IDs in an unmodifiable, caching LazyList so Objects can be retrieved on demand. The LazyList caches retrieved Objects supporting almost all List operations, at the expense of used memory. See LazyList for details.

    • findIdsWithScores

      @Nonnull public List<IdWithScore> findIdsWithScores(long offset, long limit)
      Like findIdsWithScores(), but can skip and limit results.

      Use to get a slice of the whole result, e.g. for "result paging".

      Parameters:
      offset - If greater than 0, skips this many results.
      limit - If greater than 0, returns at most this many results.

    • findIdsWithScores

      @Nonnull public List<IdWithScore> findIdsWithScores()
      Finds IDs of objects matching the query associated to their query score (e.g. distance in NN search).

      This only works on objects with a property with an HnswIndex.

      Returns:
      A list of IdWithScore that wraps IDs of matching objects and their score, sorted by score in ascending order.

    • findWithScores

      @Nonnull public List<ObjectWithScore<T>> findWithScores(long offset, long limit)
      Like findWithScores(), but can skip and limit results.

      Use to get a slice of the whole result, e.g. for "result paging".

      Parameters:
      offset - If greater than 0, skips this many results.
      limit - If greater than 0, returns at most this many results.

    • findWithScores

      @Nonnull public List<ObjectWithScore<T>> findWithScores()
      Finds objects matching the query associated to their query score (e.g. distance in NN search).

      This only works on objects with a property with an HnswIndex.

      Returns:
      A list of ObjectWithScore that wraps matching objects and their score, sorted by score in ascending order.

    • property

      public PropertyQuery property(Property<T> property)
      Creates a PropertyQuery for the given property.

      A PropertyQuery uses the same conditions as this Query object, but returns only the value(s) of a single property (not an entity objects).

      Parameters:
      property - the property for which to return values

    • forEach

      public void forEach(QueryConsumer<T> consumer)
      Emits query results one by one to the given consumer (synchronously). Once this method returns, the consumer will have received all result object). It "streams" each object from the database to the consumer, which is very memory efficient. Because this is run in a read transaction, the consumer gets a consistent view on the data. Like findLazy(), this method can be used for a high amount of data.

      Note: because the consumer is called within a read transaction it may not write to the database.

    • count

      public long count()
      Returns the count of Objects matching the query.

    • setParameter

      public Query<T> setParameter(Property<?> property, String value)
      Sets a parameter previously given to the QueryBuilder to a new value.

    • setParameter

      public Query<T> setParameter(String alias, String value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, long value)
      Sets a parameter previously given to the QueryBuilder to a new value.

    • setParameter

      public Query<T> setParameter(String alias, long value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, double value)
      Sets a parameter previously given to the QueryBuilder to a new value.

    • setParameter

      public Query<T> setParameter(String alias, double value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, Date value)
      Sets a parameter previously given to the QueryBuilder to a new value.
      Throws:
      NullPointerException - if given date is null

    • setParameter

      public Query<T> setParameter(String alias, Date value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.
      Throws:
      NullPointerException - if given date is null

    • setParameter

      public Query<T> setParameter(Property<?> property, boolean value)
      Sets a parameter previously given to the QueryBuilder to a new value.

    • setParameter

      public Query<T> setParameter(String alias, boolean value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, int[] value)
      Changes the parameter of the query condition for property to a new value.
      Parameters:
      property - Property reference from generated entity underscore class, like Example_.example.
      value - The new int[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(String alias, int[] value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new int[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, long[] value)
      Changes the parameter of the query condition for property to a new value.
      Parameters:
      property - Property reference from generated entity underscore class, like Example_.example.
      value - The new long[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(String alias, long[] value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new long[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, float[] value)
      Changes the parameter of the query condition for property to a new value.
      Parameters:
      property - Property reference from generated entity underscore class, like Example_.example.
      value - The new float[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(String alias, float[] value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new float[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, String[] value)
      Changes the parameter of the query condition for property to a new value.
      Parameters:
      property - Property reference from generated entity underscore class, like Example_.example.
      value - The new String[] value to use for the query condition.

    • setParameter

      public Query<T> setParameter(String alias, String[] value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new String[] value to use for the query condition.

    • setParameters

      public Query<T> setParameters(Property<?> property, long value1, long value2)
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      public Query<T> setParameters(String alias, long value1, long value2)
      Changes the parameters of the query condition with the matching alias to the new values.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value1 - The first value to use for the query condition.
      value2 - The second value to use for the query condition.

    • setParameters

      @Deprecated public Query<T> setParameters(Property<?> property, int[] values)
      Deprecated.
      Use setParameter(Property, int[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      @Deprecated public Query<T> setParameters(String alias, int[] values)
      Deprecated.
      Use setParameter(String, int[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.
      Parameters:
      alias - as defined using QueryBuilder.parameterAlias(String).

    • setParameters

      @Deprecated public Query<T> setParameters(Property<?> property, long[] values)
      Deprecated.
      Use setParameter(Property, long[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      @Deprecated public Query<T> setParameters(String alias, long[] values)
      Deprecated.
      Use setParameter(String, long[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.
      Parameters:
      alias - as defined using QueryBuilder.parameterAlias(String).

    • setParameters

      public Query<T> setParameters(Property<?> property, double value1, double value2)
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      public Query<T> setParameters(String alias, double value1, double value2)
      Changes the parameters of the query condition with the matching alias to the new values.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value1 - The first value to use for the query condition.
      value2 - The second value to use for the query condition.

    • setParameters

      @Deprecated public Query<T> setParameters(Property<?> property, String[] values)
      Deprecated.
      Use setParameter(Property, String[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      @Deprecated public Query<T> setParameters(String alias, String[] values)
      Deprecated.
      Use setParameter(String, String[]) instead.
      Sets a parameter previously given to the QueryBuilder to new values.
      Parameters:
      alias - as defined using QueryBuilder.parameterAlias(String).

    • setParameters

      public Query<T> setParameters(Property<?> property, String key, String value)
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameters

      public Query<T> setParameters(String alias, String key, String value)
      Changes the parameters of the query condition with the matching alias to the new values.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      key - The first value to use for the query condition.
      value - The second value to use for the query condition.

    • setParameter

      public Query<T> setParameter(Property<?> property, byte[] value)
      Sets a parameter previously given to the QueryBuilder to new values.

    • setParameter

      public Query<T> setParameter(String alias, byte[] value)
      Changes the parameter of the query condition with the matching alias to a new value.
      Parameters:
      alias - as defined using PropertyQueryCondition.alias(String).
      value - The new value to use for the query condition.

    • remove

      public long remove()
      Removes (deletes) all Objects matching the query
      Returns:
      count of removed Objects

    • subscribe

      public SubscriptionBuilder<List<T>> subscribe()
      Returns a SubscriptionBuilder to build a subscription to observe changes to the results of this query.

      Typical usage: 

       DataSubscription subscription = query.subscribe()
         .observer((List<T> data) -> {
               // Do something with the returned results
         });
 // Once the observer should no longer be notified
 subscription.cancel();
      Note that the observer will receive new results on any changes to the Box of the @Entity this queries, regardless of the conditions of this query. This is because the QueryPublisher used for the subscription observes changes by using BoxStore.subscribe(Class) on the Box this queries.

      To customize this or for advanced use cases, consider using BoxStore.subscribe(Class) directly.

      See SubscriptionBuilder.observer(DataObserver) for additional details.

      Returns:
      A SubscriptionBuilder to build a subscription.

    • subscribe

      public SubscriptionBuilder<List<T>> subscribe(DataSubscriptionList dataSubscriptionList)
      Convenience for subscribe() with a subsequent call to SubscriptionBuilder.dataSubscriptionList(DataSubscriptionList).
      Parameters:
      dataSubscriptionList - the resulting DataSubscription will be added to it

    • publish

      public void publish()
      Publishes the current data to all subscribed @DataObservers. This is useful triggering observers when new parameters have been set. Note, that setParameter methods will NOT be propagated to observers.

    • describe

      public String describe()
      For logging and testing, returns a string describing this query like "Query for entity Example with 4 conditions with properties prop1, prop2".

      Note: the format of the returned string may change without notice.

    • describeParameters

      public String describeParameters()
      For logging and testing, returns a string describing the conditions of this query like "(prop1 == A AND prop2 is null)".

      Note: the format of the returned string may change without notice.