public class Query
A Query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering.
Static Methods
fromProto(Firestore firestore, RunQueryRequest proto)
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 | |
---|---|
Name | Description |
firestore |
Firestore a Firestore instance to apply the query to |
proto |
RunQueryRequest the serialized RunQueryRequest |
Returns | |
---|---|
Type | Description |
Query |
a Query instance that can be used to execute the RunQueryRequest |
Constructors
Query(FirestoreRpcContext<?> rpcContext, Query.QueryOptions queryOptions)
protected Query(FirestoreRpcContext<?> rpcContext, Query.QueryOptions queryOptions)
Parameters | |
---|---|
Name | Description |
rpcContext |
com.google.cloud.firestore.FirestoreRpcContext<?> |
queryOptions |
com.google.cloud.firestore.Query.QueryOptions |
Methods
addSnapshotListener(EventListener<QuerySnapshot> listener)
public ListenerRegistration addSnapshotListener(EventListener<QuerySnapshot> listener)
Starts listening to this query.
Parameter | |
---|---|
Name | Description |
listener |
EventListener<QuerySnapshot> The event listener that will be called with the snapshots. |
Returns | |
---|---|
Type | Description |
ListenerRegistration |
A registration object that can be used to remove the listener. |
addSnapshotListener(Executor executor, EventListener<QuerySnapshot> listener)
public ListenerRegistration addSnapshotListener(Executor executor, EventListener<QuerySnapshot> listener)
Starts listening to this query.
Parameters | |
---|---|
Name | Description |
executor |
Executor The executor to use to call the listener. |
listener |
EventListener<QuerySnapshot> The event listener that will be called with the snapshots. |
Returns | |
---|---|
Type | Description |
ListenerRegistration |
A registration object that can be used to remove the listener. |
aggregate(AggregateField aggregateField1, AggregateField[] aggregateFields)
public AggregateQuery aggregate(AggregateField aggregateField1, AggregateField[] aggregateFields)
Calculates the specified aggregations over the documents in the result set of the given query without actually downloading the documents.
Using the returned query to perform aggregations is efficient because only the final aggregation values, not the documents' data, is downloaded. The returned query can perform aggregations of the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).
Parameters | |
---|---|
Name | Description |
aggregateField1 |
AggregateField |
aggregateFields |
AggregateField[] |
Returns | |
---|---|
Type | Description |
AggregateQuery |
an AggregateQuery that performs aggregations on the documents in the result set of this query. |
count()
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 count the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).
Returns | |
---|---|
Type | Description |
AggregateQuery |
a query that counts the documents in the result set of this query. |
endAt(DocumentSnapshot snapshot)
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.
Parameter | |
---|---|
Name | Description |
snapshot |
DocumentSnapshot The snapshot of the document to end at. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
endAt(Object[] fieldValues)
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.
Parameter | |
---|---|
Name | Description |
fieldValues |
Object[] The field values to end this query at, in order of the query's order by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
endBefore(DocumentSnapshot snapshot)
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.
Parameter | |
---|---|
Name | Description |
snapshot |
DocumentSnapshot The snapshot of the document to end before. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
endBefore(Object[] fieldValues)
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.
Parameter | |
---|---|
Name | Description |
fieldValues |
Object[] The field values to end this query before, in order of the query's order by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
equals(Object obj)
public boolean equals(Object obj)
Returns true if this Query is equal to the provided object.
Parameter | |
---|---|
Name | Description |
obj |
Object The object to compare against. |
Returns | |
---|---|
Type | Description |
boolean |
Whether this Query is equal to the provided object. |
explain(ExplainOptions options)
public ApiFuture<ExplainResults<QuerySnapshot>> explain(ExplainOptions options)
Plans and optionally executes this query. Returns an ApiFuture that will be resolved with the planner information, statistics from the query execution (if any), and the query results (if any).
Parameter | |
---|---|
Name | Description |
options |
ExplainOptions |
Returns | |
---|---|
Type | Description |
ApiFuture<ExplainResults<QuerySnapshot>> |
An ApiFuture that will be resolved with the planner information, statistics from the query execution (if any), and the query results (if any). |
explainStream(ExplainOptions options, ApiStreamObserver<DocumentSnapshot> documentObserver)
public ApiFuture<ExplainMetrics> explainStream(ExplainOptions options, ApiStreamObserver<DocumentSnapshot> documentObserver)
Executes the query, streams the results as a StreamObserver of DocumentSnapshots, and returns an ApiFuture that will be resolved with the associated ExplainMetrics.
Parameters | |
---|---|
Name | Description |
options |
ExplainOptions The options that configure the explain request. |
documentObserver |
ApiStreamObserver<DocumentSnapshot> The observer to be notified every time a new document arrives. |
Returns | |
---|---|
Type | Description |
ApiFuture<ExplainMetrics> |
get()
public ApiFuture<QuerySnapshot> get()
Executes the query and returns the results as QuerySnapshot.
Returns | |
---|---|
Type | Description |
ApiFuture<QuerySnapshot> |
An ApiFuture that will be resolved with the results of the Query. |
getFirestore()
public Firestore getFirestore()
Gets the Firestore instance associated with this query.
Returns | |
---|---|
Type | Description |
Firestore |
The Firestore instance associated with this query. |
hashCode()
public int hashCode()
Returns | |
---|---|
Type | Description |
int |
limit(int limit)
public Query limit(int limit)
Creates and returns a new Query that only returns the first matching documents.
Parameter | |
---|---|
Name | Description |
limit |
int The maximum number of items to return. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
limitToLast(int limit)
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 java.lang.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.
Parameter | |
---|---|
Name | Description |
limit |
int the maximum number of items to return |
Returns | |
---|---|
Type | Description |
Query |
the created Query |
offset(int offset)
public Query offset(int offset)
Creates and returns a new Query that skips the first n results.
Parameter | |
---|---|
Name | Description |
offset |
int The number of items to skip. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
orderBy(FieldPath fieldPath)
public Query orderBy(FieldPath fieldPath)
Creates and returns a new Query that's additionally sorted by the specified field.
Parameter | |
---|---|
Name | Description |
fieldPath |
FieldPath The field to sort by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
orderBy(FieldPath fieldPath, Query.Direction direction)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The field to sort by. |
direction |
Query.Direction The direction to sort. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
orderBy(String field)
public Query orderBy(String field)
Creates and returns a new Query that's additionally sorted by the specified field.
Parameter | |
---|---|
Name | Description |
field |
String The field to sort by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
orderBy(String field, Query.Direction direction)
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 | |
---|---|
Name | Description |
field |
String The field to sort by. |
direction |
Query.Direction The direction to sort. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
select(FieldPath[] fieldPaths)
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.
Parameter | |
---|---|
Name | Description |
fieldPaths |
FieldPath[] The field paths to include. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
select(String[] fields)
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.
Parameter | |
---|---|
Name | Description |
fields |
String[] The fields to include. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
startAfter(DocumentSnapshot snapshot)
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.
Parameter | |
---|---|
Name | Description |
snapshot |
DocumentSnapshot The snapshot of the document to start after. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
startAfter(Object[] fieldValues)
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.
Parameter | |
---|---|
Name | Description |
fieldValues |
Object[] The field values to start this query after, in order of the query's order by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
startAt(DocumentSnapshot snapshot)
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.
Parameter | |
---|---|
Name | Description |
snapshot |
DocumentSnapshot The snapshot of the document to start at. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
startAt(Object[] fieldValues)
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.
Parameter | |
---|---|
Name | Description |
fieldValues |
Object[] The field values to start this query at, in order of the query's order by. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
stream(ApiStreamObserver<DocumentSnapshot> responseObserver)
public void stream(ApiStreamObserver<DocumentSnapshot> responseObserver)
Executes the query and streams the results as a StreamObserver of DocumentSnapshots.
Parameter | |
---|---|
Name | Description |
responseObserver |
ApiStreamObserver<DocumentSnapshot> 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 | |
---|---|
Type | Description |
RunQueryRequest |
the serialized RunQueryRequest |
where(Filter filter)
public Query where(Filter filter)
Creates and returns a new Query with the additional filter.
Parameter | |
---|---|
Name | Description |
filter |
Filter The new filter to apply to the existing query. |
Returns | |
---|---|
Type | Description |
Query |
The newly created Query. |
whereArrayContains(FieldPath fieldPath, Object value)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field containing an array to search |
value |
Object The value that must be contained in the array |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereArrayContains(String field, Object value)
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 | |
---|---|
Name | Description |
field |
String The name of the field containing an array to search |
value |
Object The value that must be contained in the array |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereArrayContainsAny(FieldPath fieldPath, List<? extends Object> values)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field containing an array to search. |
values |
List<? extends java.lang.Object> A list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereArrayContainsAny(String field, List<? extends Object> values)
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 | |
---|---|
Name | Description |
field |
String The name of the field containing an array to search. |
values |
List<? extends java.lang.Object> A list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereEqualTo(FieldPath fieldPath, Object value)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereEqualTo(String field, Object value)
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 | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereGreaterThan(FieldPath fieldPath, Object value)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereGreaterThan(String field, Object value)
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 | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereGreaterThanOrEqualTo(FieldPath fieldPath, Object value)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereGreaterThanOrEqualTo(String field, Object value)
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 | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereIn(FieldPath fieldPath, List<? extends Object> values)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to search. |
values |
List<? extends java.lang.Object> A list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereIn(String field, List<? extends Object> values)
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 | |
---|---|
Name | Description |
field |
String The name of the field to search. |
values |
List<? extends java.lang.Object> A list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereLessThan(FieldPath fieldPath, Object value)
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 | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereLessThan(String field, Object value)
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 | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereLessThanOrEqualTo(FieldPath fieldPath, Object value)
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 or equal to the specified value.
Parameters | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereLessThanOrEqualTo(String field, Object value)
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 or equal to the specified value.
Parameters | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereNotEqualTo(FieldPath fieldPath, Object value)
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.
Parameters | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereNotEqualTo(String field, Object value)
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 its value does not equal the specified value.
Parameters | |
---|---|
Name | Description |
field |
String The name of the field to compare. |
value |
Object The value for comparison. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereNotIn(FieldPath fieldPath, List<? extends Object> values)
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.
A Query can have only one whereNotIn() filter, and it cannot be combined with whereArrayContains(), whereArrayContainsAny(), whereIn(), or whereNotEqualTo().
Parameters | |
---|---|
Name | Description |
fieldPath |
FieldPath The path of the field to search. |
values |
List<? extends java.lang.Object> The list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |
whereNotIn(String field, List<? extends Object> values)
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.
A Query can have only one whereNotIn() filter and it cannot be combined with whereArrayContains(), whereArrayContainsAny(), whereIn(), or whereNotEqualTo().
Parameters | |
---|---|
Name | Description |
field |
String The name of the field to search. |
values |
List<? extends java.lang.Object> The list that contains the values to match. |
Returns | |
---|---|
Type | Description |
Query |
The created Query. |