Query

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: 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
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 Firestore instance associated with this query.
int
Query
limit(long limit)
Creates and returns a new Query that's additionally limited to only return up to the specified number of documents.
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
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
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.

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 Query.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 Query.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 Query.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)

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 Firestore instance associated with this query.

public int hashCode ()

public Query limit (long limit)

Creates and returns a new Query that's additionally limited to only return up to the specified number of documents.

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.

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.

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

Send feedback about...

Need help? Visit our support page.