Package com.google.cloud.firestore

Class Query

java.lang.Object
com.google.cloud.firestore.Query
Direct Known Subclasses:
CollectionGroup, CollectionReference
@InternalExtensionOnly public class Query extends Object
A Query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Query.Direction
    The direction of a sort.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Query(com.google.cloud.firestore.FirestoreRpcContext<?> rpcContext, com.google.cloud.firestore.Query.QueryOptions queryOptions)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    ListenerRegistration
    addSnapshotListener(EventListener<QuerySnapshot> listener)
    Starts listening to this query.
    ListenerRegistration
    addSnapshotListener(Executor executor, EventListener<QuerySnapshot> listener)
    Starts listening to this query.
    AggregateQuery
    count()
    Returns a query that counts the documents in the result set of this query.
    Query
    endAt(DocumentSnapshot snapshot)
    Creates and returns a new Query that ends at the provided document (inclusive).
    Query
    endAt(Object... fieldValues)
    Creates and returns a new Query that ends at the provided fields relative to the order of the query.
    Query
    endBefore(DocumentSnapshot snapshot)
    Creates and returns a new Query that ends before the provided document (exclusive).
    Query
    endBefore(Object... fieldValues)
    Creates and returns a new Query that ends before the provided fields relative to the order of the query.
    boolean
    equals(Object obj)
    Returns true if this Query is equal to the provided object.
    static Query
    fromProto(Firestore firestore, RunQueryRequest proto)
    Returns a Query instance that can be used to execute the provided RunQueryRequest.
    com.google.api.core.ApiFuture<QuerySnapshot>
    get()
    Executes the query and returns the results as QuerySnapshot.
    Firestore
    getFirestore()
    Gets the Firestore instance associated with this query.
    int
    hashCode()
     
    Query
    limit(int limit)
    Creates and returns a new Query that only returns the first matching documents.
    Query
    limitToLast(int limit)
    Creates and returns a new Query that only returns the last matching documents.
    Query
    offset(int offset)
    Creates and returns a new Query that skips the first n results.
    Query
    orderBy(FieldPath fieldPath)
    Creates and returns a new Query that's additionally sorted by the specified field.
    Query
    orderBy(FieldPath fieldPath, Query.Direction direction)
    Creates and returns a new Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.
    Query
    orderBy(String field)
    Creates and returns a new Query that's additionally sorted by the specified field.
    Query
    orderBy(String field, Query.Direction direction)
    Creates and returns a new Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.
    Query
    select(FieldPath... fieldPaths)
    Creates and returns a new Query instance that applies a field mask to the result and returns the specified subset of fields.
    Query
    select(String... fields)
    Creates and returns a new Query instance that applies a field mask to the result and returns the specified subset of fields.
    Query
    startAfter(DocumentSnapshot snapshot)
    Creates and returns a new Query that starts after the provided document (exclusive).
    Query
    startAfter(Object... fieldValues)
    Creates and returns a new Query that starts after the provided fields relative to the order of the query.
    Query
    startAt(DocumentSnapshot snapshot)
    Creates and returns a new Query that starts at the provided document (inclusive).
    Query
    startAt(Object... fieldValues)
    Creates and returns a new Query that starts at the provided fields relative to the order of the query.
    void
    stream(com.google.api.gax.rpc.ApiStreamObserver<DocumentSnapshot> responseObserver)
    Executes the query and streams the results as a StreamObserver of DocumentSnapshots.
    RunQueryRequest
    toProto()
    Returns the RunQueryRequest that this Query instance represents.
    Query
    where(Filter filter)
    Creates and returns a new Query with the additional filter.
    Query
    whereArrayContains(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain the provided value.
    Query
    whereArrayContains(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain the provided value.
    Query
    whereArrayContainsAny(FieldPath fieldPath, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain at least one value from the provided list.
    Query
    whereArrayContainsAny(String field, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain at least one value from the provided list.
    Query
    whereEqualTo(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
    Query
    whereEqualTo(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
    Query
    whereGreaterThan(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
    Query
    whereGreaterThan(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
    Query
    whereGreaterThanOrEqualTo(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
    Query
    whereGreaterThanOrEqualTo(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
    Query
    whereIn(FieldPath fieldPath, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.
    Query
    whereIn(String field, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.
    Query
    whereLessThan(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less than the specified value.
    Query
    whereLessThan(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less than the specified value.
    Query
    whereLessThanOrEqualTo(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less or equal to the specified value.
    Query
    whereLessThanOrEqualTo(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less or equal to the specified value.
    Query
    whereNotEqualTo(FieldPath fieldPath, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal the specified value.
    Query
    whereNotEqualTo(String field, Object value)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and its value does not equal the specified value.
    Query
    whereNotIn(FieldPath fieldPath, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided list.
    Query
    whereNotIn(String field, List<? extends Object> values)
    Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided list.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Query

      protected Query(com.google.cloud.firestore.FirestoreRpcContext<?> rpcContext, com.google.cloud.firestore.Query.QueryOptions queryOptions)

  • Method Details

    • getFirestore

      @Nonnull public Firestore getFirestore()
      Gets the Firestore instance associated with this query.
      Returns:
      The Firestore instance associated with this query.

    • whereEqualTo

      @Nonnull public Query whereEqualTo(@Nonnull String field, @Nullable Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereEqualTo

      @Nonnull public Query whereEqualTo(@Nonnull FieldPath fieldPath, @Nullable Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereNotEqualTo

      @Nonnull public Query whereNotEqualTo(@Nonnull String field, @Nullable Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and its value does not equal the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereNotEqualTo

      @Nonnull public Query whereNotEqualTo(@Nonnull FieldPath fieldPath, @Nullable Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereLessThan

      @Nonnull public Query whereLessThan(@Nonnull String field, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less than the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereLessThan

      @Nonnull public Query whereLessThan(@Nonnull FieldPath fieldPath, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less than the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereLessThanOrEqualTo

      @Nonnull public Query whereLessThanOrEqualTo(@Nonnull String field, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less or equal to the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereLessThanOrEqualTo

      @Nonnull public Query whereLessThanOrEqualTo(@Nonnull FieldPath fieldPath, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be less or equal to the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereGreaterThan

      @Nonnull public Query whereGreaterThan(@Nonnull String field, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereGreaterThan

      @Nonnull public Query whereGreaterThan(@Nonnull FieldPath fieldPath, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereGreaterThanOrEqualTo

      @Nonnull public Query whereGreaterThanOrEqualTo(@Nonnull String field, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
      Parameters:
      field - The name of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereGreaterThanOrEqualTo

      @Nonnull public Query whereGreaterThanOrEqualTo(@Nonnull FieldPath fieldPath, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
      Parameters:
      fieldPath - The path of the field to compare.
      value - The value for comparison.
      Returns:
      The created Query.

    • whereArrayContains

      @Nonnull public Query whereArrayContains(@Nonnull String field, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain the provided value.

      A Query can have only one whereArrayContains() filter and it cannot be combined with whereArrayContainsAny().

      Parameters:
      field - The name of the field containing an array to search
      value - The value that must be contained in the array
      Returns:
      The created Query.

    • whereArrayContains

      @Nonnull public Query whereArrayContains(@Nonnull FieldPath fieldPath, @Nonnull Object value)
      Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain the provided value.

      A Query can have only one whereArrayContains() filter and it cannot be combined with whereArrayContainsAny().

      Parameters:
      fieldPath - The path of the field containing an array to search
      value - The value that must be contained in the array
      Returns:
      The created Query.

    • whereArrayContainsAny

      @Nonnull public Query whereArrayContainsAny(@Nonnull String field, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain at least one value from the provided list.

      A Query can have only one whereArrayContainsAny() filter and it cannot be combined with whereArrayContains() or whereIn().

      Parameters:
      field - The name of the field containing an array to search.
      values - A list that contains the values to match.
      Returns:
      The created Query.

    • whereArrayContainsAny

      @Nonnull public Query whereArrayContainsAny(@Nonnull FieldPath fieldPath, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field, the value must be an array, and that the array must contain at least one value from the provided list.

      A Query can have only one whereArrayContainsAny() filter and it cannot be combined with whereArrayContains() or whereIn().

      Parameters:
      fieldPath - The path of the field containing an array to search.
      values - A list that contains the values to match.
      Returns:
      The created Query.

    • whereIn

      @Nonnull public Query whereIn(@Nonnull String field, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.

      A Query can have only one whereIn() filter, and it cannot be combined with whereArrayContainsAny().

      Parameters:
      field - The name of the field to search.
      values - A list that contains the values to match.
      Returns:
      The created Query.

    • whereIn

      @Nonnull public Query whereIn(@Nonnull FieldPath fieldPath, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.

      A Query can have only one whereIn() filter, and it cannot be combined with whereArrayContainsAny().

      Parameters:
      fieldPath - The path of the field to search.
      values - A list that contains the values to match.
      Returns:
      The created Query.

    • whereNotIn

      @Nonnull public Query whereNotIn(@Nonnull String field, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided list.

      A Query can have only one whereNotIn() filter and it cannot be combined with whereArrayContains(), whereArrayContainsAny(), whereIn(), or whereNotEqualTo().

      Parameters:
      field - The name of the field to search.
      values - The list that contains the values to match.
      Returns:
      The created Query.

    • whereNotIn

      @Nonnull public Query whereNotIn(@Nonnull FieldPath fieldPath, @Nonnull List<? extends Object> values)
      Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided list.

      A Query can have only one whereNotIn() filter, and it cannot be combined with whereArrayContains(), whereArrayContainsAny(), whereIn(), or whereNotEqualTo().

      Parameters:
      fieldPath - The path of the field to search.
      values - The list that contains the values to match.
      Returns:
      The created Query.

    • where

      public Query where(Filter filter)
      Creates and returns a new Query with the additional filter.
      Parameters:
      filter - The new filter to apply to the existing query.
      Returns:
      The newly created Query.

    • orderBy

      @Nonnull public Query orderBy(@Nonnull String field)
      Creates and returns a new Query that's additionally sorted by the specified field.
      Parameters:
      field - The field to sort by.
      Returns:
      The created Query.

    • orderBy

      @Nonnull public Query orderBy(@Nonnull FieldPath fieldPath)
      Creates and returns a new Query that's additionally sorted by the specified field.
      Parameters:
      fieldPath - The field to sort by.
      Returns:
      The created Query.

    • orderBy

      @Nonnull public Query orderBy(@Nonnull String field, @Nonnull Query.Direction direction)
      Creates and returns a new Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.
      Parameters:
      field - The field to sort by.
      direction - The direction to sort.
      Returns:
      The created Query.

    • orderBy

      @Nonnull public Query orderBy(@Nonnull FieldPath fieldPath, @Nonnull Query.Direction direction)
      Creates and returns a new Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.
      Parameters:
      fieldPath - The field to sort by.
      direction - The direction to sort.
      Returns:
      The created Query.

    • limit

      @Nonnull public Query limit(int limit)
      Creates and returns a new Query that only returns the first matching documents.
      Parameters:
      limit - The maximum number of items to return.
      Returns:
      The created Query.

    • limitToLast

      @Nonnull public Query limitToLast(int limit)
      Creates and returns a new Query that only returns the last matching documents.

      You must specify at least one orderBy clause for limitToLast queries. Otherwise, an IllegalStateException is thrown during execution.

      Results for limitToLast() queries are only available once all documents are received. Hence, limitToLast() queries cannot be streamed via the stream(ApiStreamObserver) API.

      Parameters:
      limit - the maximum number of items to return
      Returns:
      the created Query

    • offset

      @Nonnull public Query offset(int offset)
      Creates and returns a new Query that skips the first n results.
      Parameters:
      offset - The number of items to skip.
      Returns:
      The created Query.

    • startAt

      @Nonnull public Query startAt(@Nonnull DocumentSnapshot snapshot)
      Creates and returns a new Query that starts at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.
      Parameters:
      snapshot - The snapshot of the document to start at.
      Returns:
      The created Query.

    • startAt

      @Nonnull public Query startAt(Object... fieldValues)
      Creates and returns a new Query that starts at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
      Parameters:
      fieldValues - The field values to start this query at, in order of the query's order by.
      Returns:
      The created Query.

    • select

      @Nonnull public Query select(String... fields)
      Creates and returns a new Query instance that applies a field mask to the result and returns the specified subset of fields. You can specify a list of field paths to return, or use an empty list to only return the references of matching documents.
      Parameters:
      fields - The fields to include.
      Returns:
      The created Query.

    • select

      @Nonnull public Query select(FieldPath... fieldPaths)
      Creates and returns a new Query instance that applies a field mask to the result and returns the specified subset of fields. You can specify a list of field paths to return, or use an empty list to only return the references of matching documents.
      Parameters:
      fieldPaths - The field paths to include.
      Returns:
      The created Query.

    • startAfter

      @Nonnull public Query startAfter(@Nonnull DocumentSnapshot snapshot)
      Creates and returns a new Query that starts after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.
      Parameters:
      snapshot - The snapshot of the document to start after.
      Returns:
      The created Query.

    • startAfter

      public Query startAfter(Object... fieldValues)
      Creates and returns a new Query that starts after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
      Parameters:
      fieldValues - The field values to start this query after, in order of the query's order by.
      Returns:
      The created Query.

    • endBefore

      @Nonnull public Query endBefore(@Nonnull DocumentSnapshot snapshot)
      Creates and returns a new Query that ends before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.
      Parameters:
      snapshot - The snapshot of the document to end before.
      Returns:
      The created Query.

    • endBefore

      @Nonnull public Query endBefore(Object... fieldValues)
      Creates and returns a new Query that ends before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
      Parameters:
      fieldValues - The field values to end this query before, in order of the query's order by.
      Returns:
      The created Query.

    • endAt

      @Nonnull public Query endAt(Object... fieldValues)
      Creates and returns a new Query that ends at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
      Parameters:
      fieldValues - The field values to end this query at, in order of the query's order by.
      Returns:
      The created Query.

    • endAt

      @Nonnull public Query endAt(@Nonnull DocumentSnapshot snapshot)
      Creates and returns a new Query that ends at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.
      Parameters:
      snapshot - The snapshot of the document to end at.
      Returns:
      The created Query.

    • stream

      public void stream(@Nonnull com.google.api.gax.rpc.ApiStreamObserver<DocumentSnapshot> responseObserver)
      Executes the query and streams the results as a StreamObserver of DocumentSnapshots.
      Parameters:
      responseObserver - The observer to be notified when results arrive.

    • toProto

      public RunQueryRequest toProto()
      Returns the RunQueryRequest that this Query instance represents. The request contains the serialized form of all Query constraints.

      Runtime metadata (as required for `limitToLast()` queries) is not serialized and as such, the serialized request will return the results in the original backend order.

      Returns:
      the serialized RunQueryRequest

    • fromProto

      public static Query fromProto(Firestore firestore, RunQueryRequest proto)
      Returns a Query instance that can be used to execute the provided RunQueryRequest.

      Only RunQueryRequests that pertain to the same project as the Firestore instance can be deserialized.

      Runtime metadata (as required for `limitToLast()` queries) is not restored and as such, the results for limitToLast() queries will be returned in the original backend order.

      Parameters:
      firestore - a Firestore instance to apply the query to
      proto - the serialized RunQueryRequest
      Returns:
      a Query instance that can be used to execute the RunQueryRequest

    • get

      @Nonnull public com.google.api.core.ApiFuture<QuerySnapshot> get()
      Executes the query and returns the results as QuerySnapshot.
      Returns:
      An ApiFuture that will be resolved with the results of the Query.

    • addSnapshotListener

      @Nonnull public ListenerRegistration addSnapshotListener(@Nonnull EventListener<QuerySnapshot> listener)
      Starts listening to this query.
      Parameters:
      listener - The event listener that will be called with the snapshots.
      Returns:
      A registration object that can be used to remove the listener.

    • addSnapshotListener

      @Nonnull public ListenerRegistration addSnapshotListener(@Nonnull Executor executor, @Nonnull EventListener<QuerySnapshot> listener)
      Starts listening to this query.
      Parameters:
      executor - The executor to use to call the listener.
      listener - The event listener that will be called with the snapshots.
      Returns:
      A registration object that can be used to remove the listener.

    • count

      @Nonnull public AggregateQuery count()
      Returns a query that counts the documents in the result set of this query.

      The returned query, when executed, counts the documents in the result set of this query without actually downloading the documents.

      Using the returned query to count the documents is efficient because only the final count, not the documents' data, is downloaded. The returned query can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).

      Returns:
      a query that counts the documents in the result set of this query.

    • equals

      public boolean equals(Object obj)
      Returns true if this Query is equal to the provided object.
      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare against.
      Returns:
      Whether this Query is equal to the provided object.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object