firebase::firestore::Query

#include <query.h>

A Query which you can read or listen to.

Summary

You can also construct refined Query objects by adding filters and ordering.

You cannot construct a valid Query directly; use CollectionReference methods that return a Query instead.

Inheritance

Direct Known Subclasses:firebase::firestore::CollectionReference

Constructors and Destructors

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

Public types

Direction enum
An enum for the direction of a sort.

Public functions

AddSnapshotListener(std::function< void(const QuerySnapshot &, Error, const std::string &)> callback)
Starts listening to the QuerySnapshot events referenced by this query.
AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(const QuerySnapshot &, Error, const std::string &)> callback)
Starts listening to the QuerySnapshot events referenced by this query.
Count() const
virtual AggregateQuery
Returns a query that counts the documents in the result set of this query.
EndAt(const DocumentSnapshot & snapshot) const
virtual Query
Creates and returns a new Query that ends at the provided document (inclusive).
EndAt(const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query that ends at the provided fields relative to the order of the query.
EndBefore(const DocumentSnapshot & snapshot) const
virtual Query
Creates and returns a new Query that ends before the provided document (inclusive).
EndBefore(const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query that ends before the provided fields relative to the order of the query.
Get(Source source) const
virtual Future< QuerySnapshot >
Executes the query and returns the results as a QuerySnapshot.
Limit(int32_t limit) const
virtual Query
Creates and returns a new Query that only returns the first matching documents up to the specified number.
LimitToLast(int32_t limit) const
virtual Query
Creates and returns a new Query that only returns the last matching documents up to the specified number.
OrderBy(const std::string & field, Direction direction) const
virtual Query
Creates and returns a new Query that's additionally sorted by the specified field.
OrderBy(const FieldPath & field, Direction direction) const
virtual Query
Creates and returns a new Query that's additionally sorted by the specified field.
StartAfter(const DocumentSnapshot & snapshot) const
virtual Query
Creates and returns a new Query that starts after the provided document (inclusive).
StartAfter(const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query that starts after the provided fields relative to the order of the query.
StartAt(const DocumentSnapshot & snapshot) const
virtual Query
Creates and returns a new Query that starts at the provided document (inclusive).
StartAt(const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query that starts at the provided fields relative to the order of the query.
Where(const Filter & filter) const
virtual Query
Creates and returns a new Query with the additional filter.
WhereArrayContains(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereArrayContains(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereArrayContainsAny(const std::string & field, const std::vector< FieldValue > & values) const
virtual Query
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.
WhereArrayContainsAny(const FieldPath & field, const std::vector< FieldValue > & values) const
virtual Query
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.
WhereEqualTo(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereEqualTo(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereGreaterThan(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereGreaterThan(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereGreaterThanOrEqualTo(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereGreaterThanOrEqualTo(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereIn(const std::string & field, const std::vector< FieldValue > & values) const
virtual Query
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.
WhereIn(const FieldPath & field, const std::vector< FieldValue > & values) const
virtual Query
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.
WhereLessThan(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereLessThan(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereLessThanOrEqualTo(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereLessThanOrEqualTo(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereNotEqualTo(const std::string & field, const FieldValue & value) const
virtual Query
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.
WhereNotEqualTo(const FieldPath & field, const FieldValue & value) const
virtual Query
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.
WhereNotIn(const std::string & field, const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query 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(const FieldPath & field, const std::vector< FieldValue > & values) const
virtual Query
Creates and returns a new Query 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 const Firestore *
Returns the Firestore instance associated with this query.
firestore()
virtual Firestore *
Returns the Firestore instance associated with this query.
is_valid() const
bool
Returns true if this Query is valid, false if it is not valid.
operator=(const Query & other)
Query &
Copy assignment operator.
operator=(Query && other)
Query &
Move assignment operator.

Public types

Direction

 Direction

An enum for the direction of a sort.

Public functions

AddSnapshotListener

virtual ListenerRegistration AddSnapshotListener(
  std::function< void(const QuerySnapshot &, Error, const std::string &)> callback
)

Starts listening to the QuerySnapshot 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

virtual ListenerRegistration AddSnapshotListener(
  MetadataChanges metadata_changes,
  std::function< void(const QuerySnapshot &, Error, const std::string &)> callback
)

Starts listening to the QuerySnapshot events referenced by this query.

Details
Parameters
metadata_changes
Indicates whether metadata-only changes (that is, only DocumentSnapshot::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

virtual AggregateQuery Count() 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

virtual Query EndAt(
  const DocumentSnapshot & snapshot
) const 

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 order by of this query.

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

EndAt

virtual Query EndAt(
  const std::vector< FieldValue > & values
) const 

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.

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

EndBefore

virtual Query EndBefore(
  const DocumentSnapshot & snapshot
) const 

Creates and returns a new Query 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 created Query.

EndBefore

virtual Query EndBefore(
  const std::vector< FieldValue > & values
) const 

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.

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

Get

virtual Future< QuerySnapshot > Get(
  Source source
) const 

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.

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

Limit

virtual Query Limit(
  int32_t limit
) const 

Creates and returns a new Query 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 created Query.

LimitToLast

virtual Query LimitToLast(
  int32_t limit
) const 

Creates and returns a new Query 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 created Query.

OrderBy

virtual Query OrderBy(
  const std::string & field,
  Direction direction
) const 

Creates and returns a new Query 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 created Query.

OrderBy

virtual Query OrderBy(
  const FieldPath & field,
  Direction direction
) const 

Creates and returns a new Query 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 created Query.

Query

 Query()

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

Calling any member function on an invalid Query 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(
  const Query & 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 a Query. After being moved from, a Query is equivalent to its default-constructed state.

Details
Parameters
other
Query to move data from.

StartAfter

virtual Query StartAfter(
  const DocumentSnapshot & snapshot
) const 

Creates and returns a new Query 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 created Query.

StartAfter

virtual Query StartAfter(
  const std::vector< FieldValue > & values
) const 

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.

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

StartAt

virtual Query StartAt(
  const DocumentSnapshot & snapshot
) const 

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 order by of this query.

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

StartAt

virtual Query StartAt(
  const std::vector< FieldValue > & values
) const 

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.

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

Where

virtual Query Where(
  const Filter & filter
) const 

Creates and returns a new Query with the additional filter.

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

WhereArrayContains

virtual Query WhereArrayContains(
  const std::string & field,
  const FieldValue & value
) const 

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() or WhereIn().

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

WhereArrayContains

virtual Query WhereArrayContains(
  const FieldPath & field,
  const FieldValue & value
) const 

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() or WhereIn().

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

WhereArrayContainsAny

virtual Query WhereArrayContainsAny(
  const std::string & field,
  const std::vector< FieldValue > & values
) const 

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

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

WhereArrayContainsAny

virtual Query WhereArrayContainsAny(
  const FieldPath & field,
  const std::vector< FieldValue > & values
) const 

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 withWhereArrayContains() or WhereIn().

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

WhereEqualTo

virtual Query WhereEqualTo(
  const std::string & field,
  const FieldValue & value
) const 

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.

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

WhereEqualTo

virtual Query WhereEqualTo(
  const FieldPath & field,
  const FieldValue & value
) const 

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.

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

WhereGreaterThan

virtual Query WhereGreaterThan(
  const std::string & field,
  const FieldValue & value
) const 

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.

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

WhereGreaterThan

virtual Query WhereGreaterThan(
  const FieldPath & field,
  const FieldValue & value
) const 

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.

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

WhereGreaterThanOrEqualTo

virtual Query WhereGreaterThanOrEqualTo(
  const std::string & field,
  const FieldValue & value
) const 

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.

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

WhereGreaterThanOrEqualTo

virtual Query WhereGreaterThanOrEqualTo(
  const FieldPath & field,
  const FieldValue & value
) const 

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.

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

WhereIn

virtual Query WhereIn(
  const std::string & field,
  const std::vector< FieldValue > & values
) const 

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

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

WhereIn

virtual Query WhereIn(
  const FieldPath & field,
  const std::vector< FieldValue > & values
) const 

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

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

WhereLessThan

virtual Query WhereLessThan(
  const std::string & field,
  const FieldValue & value
) const 

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.

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

WhereLessThan

virtual Query WhereLessThan(
  const FieldPath & field,
  const FieldValue & value
) const 

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.

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

WhereLessThanOrEqualTo

virtual Query WhereLessThanOrEqualTo(
  const std::string & field,
  const FieldValue & value
) const 

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.

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

WhereLessThanOrEqualTo

virtual Query WhereLessThanOrEqualTo(
  const FieldPath & field,
  const FieldValue & value
) const 

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.

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

WhereNotEqualTo

virtual Query WhereNotEqualTo(
  const std::string & field,
  const FieldValue & value
) const 

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

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

WhereNotEqualTo

virtual Query WhereNotEqualTo(
  const FieldPath & field,
  const FieldValue & value
) const 

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

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

WhereNotIn

virtual Query WhereNotIn(
  const std::string & field,
  const std::vector< FieldValue > & values
) const 

Creates and returns a new Query 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 that WhereNotIn cannot match FieldValue::Null() values. To query for documents where a field exists and is FieldValue::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().

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

WhereNotIn

virtual Query WhereNotIn(
  const FieldPath & field,
  const std::vector< FieldValue > & values
) const 

Creates and returns a new Query 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 that WhereNotIn cannot match FieldValue::Null() values. To query for documents where a field exists and is FieldValue::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().

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

firestore

virtual const Firestore * firestore() const 

Returns the Firestore instance associated with this query.

The pointer will remain valid indefinitely.

Details
Returns
Firebase Firestore instance that this Query refers to.

firestore

virtual Firestore * firestore()

Returns the Firestore instance associated with this query.

The pointer will remain valid indefinitely.

Details
Returns
Firebase Firestore instance that this Query refers to.

is_valid

bool is_valid() const 

Returns true if this Query is valid, false if it is not valid.

An invalid Query could be the result of:

  • Creating a Query using the default constructor.
  • Moving from the Query.
  • Deleting your Firestore instance, which will invalidate all the Query instances associated with it.

Details
Returns
true if this Query is valid, false if this Query is invalid.

operator=

Query & operator=(
  const Query & other
)

Copy assignment operator.

Query is immutable and can be efficiently copied.

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

operator=

Query & operator=(
  Query && other
)

Move assignment operator.

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

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

~Query

virtual  ~Query()