firebase::firestore::Query

#include <query.h>

AQuery which you can read or listen to.

Summary

You can also construct refinedQuery objects by adding filters and ordering.

You cannot construct a validQuery directly; useCollectionReference methods that return aQuery instead.

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.

Inheritance

Direct Known Subclasses:firebase::firestore::CollectionReference

Constructors and Destructors

Query()
Creates an invalidQuery that has to be reassigned before it can be used.
Query(constQuery & other)
Copy constructor.
Query(Query && other)
Move constructor.
~Query()

Public types

Directionenum
An enum for the direction of a sort.

Public functions

AddSnapshotListener(std::function< void(constQuerySnapshot &,Error, const std::string &)> callback)
Starts listening to theQuerySnapshot events referenced by this query.
AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(constQuerySnapshot &,Error, const std::string &)> callback)
Starts listening to theQuerySnapshot events referenced by this query.
Count() const
Returns a query that counts the documents in the result set of this query.
EndAt(constDocumentSnapshot & snapshot) const
virtualQuery
Creates and returns a newQuery that ends at the provided document (inclusive).
EndAt(const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery that ends at the provided fields relative to the order of the query.
EndBefore(constDocumentSnapshot & snapshot) const
virtualQuery
Creates and returns a newQuery that ends before the provided document (inclusive).
EndBefore(const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery that ends before the provided fields relative to the order of the query.
Get(Source source) const
Executes the query and returns the results as aQuerySnapshot.
Limit(int32_t limit) const
virtualQuery
Creates and returns a newQuery that only returns the first matching documents up to the specified number.
LimitToLast(int32_t limit) const
virtualQuery
Creates and returns a newQuery that only returns the last matching documents up to the specified number.
OrderBy(const std::string & field,Direction direction) const
virtualQuery
Creates and returns a newQuery that's additionally sorted by the specified field.
OrderBy(constFieldPath & field,Direction direction) const
virtualQuery
Creates and returns a newQuery that's additionally sorted by the specified field.
StartAfter(constDocumentSnapshot & snapshot) const
virtualQuery
Creates and returns a newQuery that starts after the provided document (inclusive).
StartAfter(const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery that starts after the provided fields relative to the order of the query.
StartAt(constDocumentSnapshot & snapshot) const
virtualQuery
Creates and returns a newQuery that starts at the provided document (inclusive).
StartAt(const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery that starts at the provided fields relative to the order of the query.
Where(constFilter & filter) const
virtualQuery
Creates and returns a newQuery with the additional filter.
WhereArrayContains(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery 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.
WhereArrayContains(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery 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.
WhereArrayContainsAny(const std::string & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery 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.
WhereArrayContainsAny(constFieldPath & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery 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.
WhereEqualTo(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
WhereEqualTo(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be equal to the specified value.
WhereGreaterThan(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
WhereGreaterThan(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than the specified value.
WhereGreaterThanOrEqualTo(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
WhereGreaterThanOrEqualTo(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.
WhereIn(const std::string & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.
WhereIn(constFieldPath & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.
WhereLessThan(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than the specified value.
WhereLessThan(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than the specified value.
WhereLessThanOrEqualTo(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than or equal to the specified value.
WhereLessThanOrEqualTo(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than or equal to the specified value.
WhereNotEqualTo(const std::string & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value does not equal the specified value.
WhereNotEqualTo(constFieldPath & field, constFieldValue & value) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value does not equal the specified value.
WhereNotIn(const std::string & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must not equal any of the values from the provided list.
WhereNotIn(constFieldPath & field, const std::vector<FieldValue > & values) const
virtualQuery
Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must not equal any of the values from the provided list.
firestore() const
virtual constFirestore *
Returns theFirestore instance associated with this query.
firestore()
virtualFirestore *
Returns theFirestore instance associated with this query.
is_valid() const
bool
Returns true if thisQuery is valid, false if it is not valid.
operator=(constQuery & other)
Copy assignment operator.
operator=(Query && other)
Move assignment operator.

Public types

Direction

Direction

An enum for the direction of a sort.

Public functions

AddSnapshotListener

virtualListenerRegistrationAddSnapshotListener(std::function<void(constQuerySnapshot&,Error,conststd::string&)>callback)

Starts listening to theQuerySnapshot events referenced by this query.

Details
Parameters
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

AddSnapshotListener

virtualListenerRegistrationAddSnapshotListener(MetadataChangesmetadata_changes,std::function<void(constQuerySnapshot&,Error,conststd::string&)>callback)

Starts listening to theQuerySnapshot events referenced by this query.

Details
Parameters
metadata_changes
Indicates whether metadata-only changes (that is, onlyDocumentSnapshot::metadata() changed) should trigger snapshot events.
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

Count

virtualAggregateQueryCount()const

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

Details
Returns
An aggregate query that counts the documents in the result set of this query.

EndAt

virtualQueryEndAt(constDocumentSnapshot&snapshot)const

Creates and returns a newQuery 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 order by of this query.

Details
Parameters
snapshot
The snapshot of the document to end at.
Returns
The createdQuery.

EndAt

virtualQueryEndAt(conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

Details
Parameters
values
The field values to end this query at, in order of the query's order by.
Returns
The createdQuery.

EndBefore

virtualQueryEndBefore(constDocumentSnapshot&snapshot)const

Creates and returns a newQuery that ends before 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 order by of this query.

Details
Parameters
snapshot
The snapshot of the document to end before.
Returns
The createdQuery.

EndBefore

virtualQueryEndBefore(conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

Details
Parameters
values
The field values to end this query before, in order of the query's order by.
Returns
The createdQuery.

Get

virtualFuture<QuerySnapshot>Get(Sourcesource)const

Executes the query and returns the results as aQuerySnapshot.

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.

Details
Parameters
source
A value to configure the get behavior (optional).
Returns
AFuture that will be resolved with the results of theQuery.

Limit

virtualQueryLimit(int32_tlimit)const

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

Details
Parameters
limit
A non-negative integer to specify the maximum number of items to return.
Returns
The createdQuery.

LimitToLast

virtualQueryLimitToLast(int32_tlimit)const

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

Details
Parameters
limit
A non-negative integer to specify the maximum number of items to return.
Returns
The createdQuery.

OrderBy

virtualQueryOrderBy(conststd::string&field,Directiondirection)const

Creates and returns a newQuery that's additionally sorted by the specified field.

Details
Parameters
field
The field to sort by.
direction
The direction to sort (optional). If not specified, order will be ascending.
Returns
The createdQuery.

OrderBy

virtualQueryOrderBy(constFieldPath&field,Directiondirection)const

Creates and returns a newQuery that's additionally sorted by the specified field.

Details
Parameters
field
The field to sort by.
direction
The direction to sort (optional). If not specified, order will be ascending.
Returns
The createdQuery.

Query

Query()

Creates an invalidQuery that has to be reassigned before it can be used.

Calling any member function on an invalidQuery will be a no-op. If the function returns a value, it will return a zero, empty, or invalid value, depending on the type of the value.

Query

Query(constQuery&other)

Copy constructor.

Query is immutable and can be efficiently copied.

Details
Parameters
other
Query to copy from.

Query

Query(Query&&other)

Move constructor.

Moving is more efficient than copying for aQuery. After being moved from, aQuery is equivalent to its default-constructed state.

Details
Parameters
other
Query to move data from.

StartAfter

virtualQueryStartAfter(constDocumentSnapshot&snapshot)const

Creates and returns a newQuery that starts after 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 order by of this query.

Details
Parameters
snapshot
The snapshot of the document to start after.
Returns
The createdQuery.

StartAfter

virtualQueryStartAfter(conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

Details
Parameters
values
The field values to start this query after, in order of the query's order by.
Returns
The createdQuery.

StartAt

virtualQueryStartAt(constDocumentSnapshot&snapshot)const

Creates and returns a newQuery 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 order by of this query.

Details
Parameters
snapshot
The snapshot of the document to start at.
Returns
The createdQuery.

StartAt

virtualQueryStartAt(conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

Details
Parameters
values
The field values to start this query at, in order of the query's order by.
Returns
The createdQuery.

Where

virtualQueryWhere(constFilter&filter)const

Creates and returns a newQuery with the additional filter.

Details
Parameters
filter
The new filter to apply to the existing query.
Returns
The createdQuery.

WhereArrayContains

virtualQueryWhereArrayContains(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery 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.

AQuery can have only oneWhereArrayContains() filter and it cannot be combined withWhereArrayContainsAny() orWhereIn().

Details
Parameters
field
The name of the field containing an array to search.
value
The value that must be contained in the array.
Returns
The createdQuery.

WhereArrayContains

virtualQueryWhereArrayContains(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery 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.

AQuery can have only oneWhereArrayContains() filter and it cannot be combined withWhereArrayContainsAny() orWhereIn().

Details
Parameters
field
The path of the field containing an array to search.
value
The value that must be contained in the array.
Returns
The createdQuery.

WhereArrayContainsAny

virtualQueryWhereArrayContainsAny(conststd::string&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

AQuery can have only oneWhereArrayContainsAny() filter and it cannot be combined withWhereArrayContains() orWhereIn().

Details
Parameters
field
The name of the field containing an array to search.
values
The list that contains the values to match.
Returns
The createdQuery.

WhereArrayContainsAny

virtualQueryWhereArrayContainsAny(constFieldPath&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery 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.

AQuery can have only oneWhereArrayContainsAny() filter and it cannot be combined withWhereArrayContains() orWhereIn().

Details
Parameters
field
The path of the field containing an array to search.
values
The list that contains the values to match.
Returns
The createdQuery.

WhereEqualTo

virtualQueryWhereEqualTo(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be equal to the specified value.

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereEqualTo

virtualQueryWhereEqualTo(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be equal to the specified value.

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereGreaterThan

virtualQueryWhereGreaterThan(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than the specified value.

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereGreaterThan

virtualQueryWhereGreaterThan(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than the specified value.

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereGreaterThanOrEqualTo

virtualQueryWhereGreaterThanOrEqualTo(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereGreaterThanOrEqualTo

virtualQueryWhereGreaterThanOrEqualTo(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be greater than or equal to the specified value.

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereIn

virtualQueryWhereIn(conststd::string&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.

AQuery can have only oneWhereIn() filter and it cannot be combined withWhereArrayContainsAny().

Details
Parameters
field
The name of the field to compare.
values
The list that contains the values to match.
Returns
The createdQuery.

WhereIn

virtualQueryWhereIn(constFieldPath&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must equal one of the values from the provided list.

AQuery can have only oneWhereIn() filter and it cannot be combined withWhereArrayContainsAny().

Details
Parameters
field
The path of the field to compare.
values
The list that contains the values to match.
Returns
The createdQuery.

WhereLessThan

virtualQueryWhereLessThan(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than the specified value.

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereLessThan

virtualQueryWhereLessThan(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than the specified value.

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereLessThanOrEqualTo

virtualQueryWhereLessThanOrEqualTo(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than or equal to the specified value.

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereLessThanOrEqualTo

virtualQueryWhereLessThanOrEqualTo(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value should be less than or equal to the specified value.

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereNotEqualTo

virtualQueryWhereNotEqualTo(conststd::string&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value does not equal the specified value.

AQuery can have only oneWhereNotEqualTo() filter, and it cannot be combined withWhereNotIn().

Details
Parameters
field
The name of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereNotEqualTo

virtualQueryWhereNotEqualTo(constFieldPath&field,constFieldValue&value)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value does not equal the specified value.

AQuery can have only oneWhereNotEqualTo() filter, and it cannot be combined withWhereNotIn().

Details
Parameters
field
The path of the field to compare.
value
The value for comparison.
Returns
The createdQuery.

WhereNotIn

virtualQueryWhereNotIn(conststd::string&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must not equal any of the values from the provided list.

One special case is thatWhereNotIn cannot matchFieldValue::Null() values. To query for documents where a field exists and isFieldValue::Null(), useWhereNotEqualTo, which can handle this special case.

AQuery can have only oneWhereNotIn() filter, and it cannot be combined withWhereArrayContains(),WhereArrayContainsAny(),WhereIn(), orWhereNotEqualTo().

Details
Parameters
field
The name of the field to compare.
values
The list that contains the values to match.
Returns
The createdQuery.

WhereNotIn

virtualQueryWhereNotIn(constFieldPath&field,conststd::vector<FieldValue>&values)const

Creates and returns a newQuery with the additional filter that documents must contain the specified field and the value must not equal any of the values from the provided list.

One special case is thatWhereNotIn cannot matchFieldValue::Null() values. To query for documents where a field exists and isFieldValue::Null(), useWhereNotEqualTo, which can handle this special case.

AQuery can have only oneWhereNotIn() filter, and it cannot be combined withWhereArrayContains(),WhereArrayContainsAny(),WhereIn(), orWhereNotEqualTo().

Details
Parameters
field
The path of the field to compare.
values
The list that contains the values to match.
Returns
The createdQuery.

firestore

virtualconstFirestore*firestore()const

Returns theFirestore instance associated with this query.

The pointer will remain valid indefinitely.

Details
Returns
FirebaseFirestore instance that thisQuery refers to.

firestore

virtualFirestore*firestore()

Returns theFirestore instance associated with this query.

The pointer will remain valid indefinitely.

Details
Returns
FirebaseFirestore instance that thisQuery refers to.

is_valid

boolis_valid()const

Returns true if thisQuery is valid, false if it is not valid.

An invalidQuery could be the result of:

  • Creating aQuery using the default constructor.
  • Moving from theQuery.
  • Deleting yourFirestore instance, which will invalidate all theQuery instances associated with it.

Details
Returns
true if thisQuery is valid, false if thisQuery is invalid.

operator=

Query&operator=(constQuery&other)

Copy assignment operator.

Query is immutable and can be efficiently copied.

Details
Parameters
other
Query to copy from.
Returns
Reference to the destinationQuery.

operator=

Query&operator=(Query&&other)

Move assignment operator.

Moving is more efficient than copying for aQuery. After being moved from, aQuery is equivalent to its default-constructed state.

Details
Parameters
other
Query to move data from.
Returns
Reference to the destinationQuery.

~Query

virtual~Query()

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-01-23 UTC.