public class Query extends Object
Known Direct Subclasses

A Query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering.

Subclassing Note: Cloud Firestore classes are not meant to be subclassed except for use in test mocks. Subclassing is not supported in production code and new SDK releases may break code that does so.

Nested Class Summary

enum Query.Direction An enum for the direction of a sort. 

Public Method Summary

ListenerRegistration
addSnapshotListener(Activity activity, EventListener<QuerySnapshot> listener)
Starts listening to this query using an Activity-scoped listener.
ListenerRegistration
addSnapshotListener(MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)
Starts listening to this query with the given options.
ListenerRegistration
addSnapshotListener(Executor executor, EventListener<QuerySnapshot> listener)
Starts listening to this query.
ListenerRegistration
addSnapshotListener(Executor executor, MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)
Starts listening to this query with the given options.
ListenerRegistration
addSnapshotListener(Activity activity, MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)
Starts listening to this query with the given options, using an Activity-scoped listener.
ListenerRegistration
addSnapshotListener(EventListener<QuerySnapshot> listener)
Starts listening to 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 o)
Task<QuerySnapshot>
get()
Executes the query and returns the results as a QuerySnapshot.
Task<QuerySnapshot>
get(Source source)
Executes the query and returns the results as a QuerySnapshot.
FirebaseFirestore
getFirestore()
Gets the Cloud Firestore instance associated with this query.
int
hashCode()
Query
limit(long limit)
Creates and returns a new Query that only returns the first matching documents up to the specified number.
Query
limitToLast(long limit)
Creates and returns a new Query that only returns the last matching documents up to the specified number.
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
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
startAfter(Object... fieldValues)
Creates and returns a new Query that starts after the provided fields relative to the order of the query.
Query
startAfter(DocumentSnapshot snapshot)
Creates and returns a new Query that starts after the provided document (exclusive).
Query
startAt(Object... fieldValues)
Creates and returns a new Query that starts at 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
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(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
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
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(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
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
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(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
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
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 than 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 than 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 the value does not equal the specified value.
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.
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.

Inherited Method Summary

Public Methods

public ListenerRegistration addSnapshotListener (Activity activity, EventListener<QuerySnapshot> listener)

Starts listening to this query using an Activity-scoped listener.

The listener will be automatically removed during onStop().

Parameters
activity The activity to scope the listener to.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)

Starts listening to this query with the given options.

Parameters
metadataChanges Indicates whether metadata-only changes (i.e. only QuerySnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (Executor executor, 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.

public ListenerRegistration addSnapshotListener (Executor executor, MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)

Starts listening to this query with the given options.

Parameters
executor The executor to use to call the listener.
metadataChanges Indicates whether metadata-only changes (i.e. only QuerySnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (Activity activity, MetadataChanges metadataChanges, EventListener<QuerySnapshot> listener)

Starts listening to this query with the given options, using an Activity-scoped listener.

The listener will be automatically removed during onStop().

Parameters
activity The activity to scope the listener to.
metadataChanges Indicates whether metadata-only changes (i.e. only QuerySnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (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.

public Query endAt (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.

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.

public Query endBefore (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.

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.

public boolean equals (Object o)

Parameters
o

public Task<QuerySnapshot> get ()

Executes the query and returns the results as a QuerySnapshot.

Returns
  • A Task that will be resolved with the results of the Query.

public Task<QuerySnapshot> get (Source source)

Executes the query and returns the results as a QuerySnapshot.

By default, get() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. This behavior can be altered via the Source parameter.

Parameters
source A value to configure the get behavior.
Returns
  • A Task that will be resolved with the results of the Query.

public FirebaseFirestore getFirestore ()

Gets the Cloud Firestore instance associated with this query.

public int hashCode ()

public Query limit (long limit)

Creates and returns a new Query that only returns the first matching documents up to the specified number.

Parameters
limit The maximum number of items to return.
Returns
  • The created Query.

public Query limitToLast (long limit)

Creates and returns a new Query that only returns the last matching documents up to the specified number.

You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution.

Parameters
limit The maximum number of items to return.
Returns
  • The created Query.

public 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.

Parameters
field The field to sort by.
direction The direction to sort.
Returns
  • The created Query.

public Query orderBy (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.

public 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.

Parameters
fieldPath The field to sort by.
direction The direction to sort.
Returns
  • The created Query.

public Query orderBy (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.

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.

public Query startAfter (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.

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.

public Query startAt (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.

public 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.

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.

public 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.

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.

public 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.

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 The list that contains the values to match.
Returns
  • The created Query.

public 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.

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 The list that contains the values to match.
Returns
  • The created Query.

public 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.

Parameters
field The name of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
fieldPath The path of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
fieldPath The path of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
field The name of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
field The name of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
fieldPath The path of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

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 The list that contains the values to match.
Returns
  • The created Query.

public 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.

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 The list that contains the values to match.
Returns
  • The created Query.

public 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.

Parameters
field The name of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

Parameters
fieldPath The path of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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 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.

public 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 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.

public 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.

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

Parameters
fieldPath The path of the field to compare
value The value for comparison
Returns
  • The created Query.

public Query whereNotEqualTo (String field, 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.

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

Parameters
field The name of the field to compare
value The value for comparison
Returns
  • The created Query.

public 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.

One special case is that whereNotIn cannot match null values. To query for documents where a field exists and is null, use whereNotEqualTo, which can handle this special case.

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.

public 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.

One special case is that whereNotIn cannot match null values. To query for documents where a field exists and is null, use whereNotEqualTo, which can handle this special case.

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.