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)`	`virtual ListenerRegistration` Starts listening to the QuerySnapshot events referenced by this query.
`AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(const QuerySnapshot &, Error, const std::string &)> callback)`	`virtual ListenerRegistration` 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

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.

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

firebase::firestore::Query

Summary

Inheritance

Constructors and Destructors

Public types

Public functions

Public types

Direction

Public functions

AddSnapshotListener

AddSnapshotListener

Count

EndAt

EndAt

EndBefore

EndBefore

Get

Limit

LimitToLast

OrderBy

OrderBy

Query

Query

Query

StartAfter

StartAfter

StartAt

StartAt

Where

WhereArrayContains

WhereArrayContains

WhereArrayContainsAny

WhereArrayContainsAny

WhereEqualTo

WhereEqualTo

WhereGreaterThan

WhereGreaterThan

WhereGreaterThanOrEqualTo

WhereGreaterThanOrEqualTo

WhereIn

WhereIn

WhereLessThan

WhereLessThan

WhereLessThanOrEqualTo

WhereLessThanOrEqualTo

WhereNotEqualTo

WhereNotEqualTo

WhereNotIn

WhereNotIn

firestore

firestore

is_valid

operator=

operator=

~Query