Firestore API - Class Query (3.12.0) 

public class Query : IEquatable<Query>

Reference documentation and code samples for the Firestore API class Query.

A query against a collection.

Inheritance

object > Query

Implements

IEquatableQuery

Derived Types

Namespace

Google.Cloud.Firestore

Assembly

Google.Cloud.Firestore.dll

Remarks

CollectionReference derives from this class as a "return-all" query against the collection it refers to.

Properties

Database

public virtual FirestoreDb Database { get; }

The database this query will search over.

Property Value
Type Description
FirestoreDb

Methods

Aggregate(AggregateField, params AggregateField[])

public AggregateQuery Aggregate(AggregateField aggregateField, params AggregateField[] aggregateFields)

Calculates the specified aggregations to return the aggregate query. Multiple aggregations can be performed in a single query.

Parameters
Name Description
aggregateField AggregateField

Specifies the AggregateField to be calculated. Must not be null.
aggregateFields AggregateField

Additional aggregations to be included in the query, if any. Must not be null, but may be empty.
Returns
Type Description
AggregateQuery

Returns an AggregateQuery that performs aggregations on the documents in the result set of this query.

Aggregate(IEnumerable<AggregateField>)

public AggregateQuery Aggregate(IEnumerable<AggregateField> aggregateFields)

Calculates the specified aggregations to return the aggregate query. Multiple aggregations can be performed in a single query.

Parameter
Name Description
aggregateFields IEnumerableAggregateField

Aggregations to be included in the query. Must not be null, or empty.
Returns
Type Description
AggregateQuery

Returns an AggregateQuery that performs aggregations on the documents in the result set of this query.

Count()

public AggregateQuery Count()

Returns an AggregateQuery with count(*) aggregation applied on this query.

Returns
Type Description
AggregateQuery

An instance of AggregateQuery with count(*) aggregation applied.

EndAt(DocumentSnapshot)

public Query EndAt(DocumentSnapshot snapshot)

Creates and returns a new query that ends at the document snapshot provided fields relative to the order of the query.

Parameter
Name Description
snapshot DocumentSnapshot

The snapshot of the document to end at.
Returns
Type Description
Query

A new query based on the current one, but with the specified end position.
Remarks

This call replaces any previously specified end position in the query.

EndAt(params object[])

public Query EndAt(params 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. Must not be null or empty, or have more values than query has orderings.
Returns
Type Description
Query

A new query based on the current one, but with the specified end position.
Remarks

This call replaces any previously specified end position in the query.

EndBefore(DocumentSnapshot)

public Query EndBefore(DocumentSnapshot snapshot)

Creates and returns a new query that ends before the document snapshot provided fields relative to the order of the query.

Parameter
Name Description
snapshot DocumentSnapshot

The snapshot of the document to end before. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the specified end position.
Remarks

This call replaces any previously specified end position in the query.

EndBefore(params object[])

public Query EndBefore(params 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. Must not be null or empty, or have more values than query has orderings.
Returns
Type Description
Query

A new query based on the current one, but with the specified end position.
Remarks

This call replaces any previously specified end position in the query.

ExplainAsync(ExplainOptions, CancellationToken)

public Task<ExplainResults<QuerySnapshot>> ExplainAsync(ExplainOptions options, CancellationToken cancellationToken = default)

Returns an explanation for this query, optionally executing it.

Parameters
Name Description
options ExplainOptions

The ExplainOptions to use. Must not be null.
cancellationToken CancellationToken

A cancellation token for the operation.
Returns
Type Description
TaskExplainResultsQuerySnapshot

A Google.Cloud.Firestore.V1.PlanSummary for this query.

GetHashCode()

public override int GetHashCode()
Returns
Type Description
int
Overrides

GetSnapshotAsync(CancellationToken)

public Task<QuerySnapshot> GetSnapshotAsync(CancellationToken cancellationToken = default)

Asynchronously takes a snapshot of all documents matching the query.

Parameter
Name Description
cancellationToken CancellationToken

A cancellation token for the operation.
Returns
Type Description
TaskQuerySnapshot

A snapshot of documents matching the query.

Limit(int)

public Query Limit(int limit)

Specifies the maximum number of results to return.

Parameter
Name Description
limit int

The maximum number of results to return. Must be greater than or equal to 0.
Returns
Type Description
Query

A new query based on the current one, but with the specified limit applied.
Remarks

This call replaces any previously-specified limit in the query.

LimitToLast(int)

public Query LimitToLast(int limit)

Creates and returns a new query that only returns the last limit matching documents.

Parameter
Name Description
limit int

The maximum number of results to return. Must be greater than or equal to 0.
Returns
Type Description
Query

A new query based on the current one, but with the specified limit applied.
Remarks

You must specify at least one OrderBy(string) clause for limit-to-last queries. Otherwise, an InvalidOperationException is thrown during execution.

Results for limit-to-last queries are only available once all documents are received, which means that these queries cannot be streamed using the StreamAsync(CancellationToken) method.

Listen(Action<QuerySnapshot>, CancellationToken)

public FirestoreChangeListener Listen(Action<QuerySnapshot> callback, CancellationToken cancellationToken = default)

Listen to this query for changes. This method is a convenience method over Listen(Func<QuerySnapshot, CancellationToken, Task>, CancellationToken), wrapping a synchronous callback to create an asynchronous one.

Parameters
Name Description
callback ActionQuerySnapshot

The callback to invoke each time the query results change. Must not be null.
cancellationToken CancellationToken

Optional cancellation token which may be used to cancel the listening operation.
Returns
Type Description
FirestoreChangeListener

A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

Listen(Func<QuerySnapshot, CancellationToken, Task>, CancellationToken)

public FirestoreChangeListener Listen(Func<QuerySnapshot, CancellationToken, Task> callback, CancellationToken cancellationToken = default)

Listen to this query for changes.

Parameters
Name Description
callback FuncQuerySnapshotCancellationTokenTask

The callback to invoke each time the query results change. Must not be null.
cancellationToken CancellationToken

Optional cancellation token which may be used to cancel the listening operation.
Returns
Type Description
FirestoreChangeListener

A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

Offset(int)

public Query Offset(int offset)

Specifies a number of results to skip.

Parameter
Name Description
offset int

The number of results to skip. Must be greater than or equal to 0.
Returns
Type Description
Query

A new query based on the current one, but with the specified offset applied.
Remarks

This call replaces any previously-specified offset in the query.

OrderBy(FieldPath)

public Query OrderBy(FieldPath fieldPath)

Adds an additional ascending ordering by the specified path.

Parameter
Name Description
fieldPath FieldPath

The field path to order by. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified ordering applied.
Remarks

Unlike LINQ's OrderBy method, this call adds additional subordinate orderings to any additionally specified. So query.OrderBy("foo").OrderBy("bar") is similar to a LINQ query.OrderBy(x => x.Foo).ThenBy(x => x.Bar).

This method cannot be called after a start/end cursor has been specified with StartAt(params object[]), StartAfter(params object[]), EndAt(params object[]) or EndBefore(params object[]).

OrderBy(string)

public Query OrderBy(string fieldPath)

Adds an additional ascending ordering by the specified path.

Parameter
Name Description
fieldPath string

The dot-separated field path to order by. Must not be null or empty.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified ordering applied.
Remarks

Unlike LINQ's OrderBy method, this call adds additional subordinate orderings to any additionally specified. So query.OrderBy("foo").OrderBy("bar") is similar to a LINQ query.OrderBy(x => x.Foo).ThenBy(x => x.Bar).

This method cannot be called after a start/end cursor has been specified with StartAt(params object[]), StartAfter(params object[]), EndAt(params object[]) or EndBefore(params object[]).

OrderByDescending(FieldPath)

public Query OrderByDescending(FieldPath fieldPath)

Adds an additional descending ordering by the specified path.

Parameter
Name Description
fieldPath FieldPath

The field path to order by. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified ordering applied.
Remarks

Unlike LINQ's OrderBy method, this call adds additional subordinate orderings to any additionally specified. So query.OrderBy("foo").OrderByDescending("bar") is similar to a LINQ query.OrderBy(x => x.Foo).ThenByDescending(x => x.Bar).

This method cannot be called after a start/end cursor has been specified with StartAt(params object[]), StartAfter(params object[]), EndAt(params object[]) or EndBefore(params object[]).

OrderByDescending(string)

public Query OrderByDescending(string fieldPath)

Adds an additional descending ordering by the specified path.

Parameter
Name Description
fieldPath string

The dot-separated field path to order by. Must not be null or empty.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified ordering applied.
Remarks

Unlike LINQ's OrderBy method, this call adds additional subordinate orderings to any additionally specified. So query.OrderBy("foo").OrderByDescending("bar") is similar to a LINQ query.OrderBy(x => x.Foo).ThenByDescending(x => x.Bar).

This method cannot be called after a start/end cursor has been specified with StartAt(params object[]), StartAfter(params object[]), EndAt(params object[]) or EndBefore(params object[]).

Select(params FieldPath[])

public Query Select(params FieldPath[] fieldPaths)

Specifies the field paths to return in the results.

Parameter
Name Description
fieldPaths FieldPath

The field paths to select. Must not be null or contain null elements. If this is empty, the document ID is implicitly selected.
Returns
Type Description
Query

A new query based on the current one, but with the specified projection applied.
Remarks

This call replaces any previously-specified projections in the query.

Select(params string[])

public Query Select(params string[] fieldPaths)

Specifies the field paths to return in the results.

Parameter
Name Description
fieldPaths string

The dot-separated field paths to select. Must not be null or empty, or contain null or empty elements.
Returns
Type Description
Query

A new query based on the current one, but with the specified projection applied.
Remarks

This call replaces any previously-specified projections in the query.

StartAfter(DocumentSnapshot)

public Query StartAfter(DocumentSnapshot snapshot)

Creates and returns a new query that starts after the document snapshot provided fields relative to the order of the query.

Parameter
Name Description
snapshot DocumentSnapshot

The snapshot of the document to start after. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the specified start position.
Remarks

This call replaces any previously specified start position in the query.

StartAfter(params object[])

public Query StartAfter(params 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. Must not be null or empty, or have more values than query has orderings.
Returns
Type Description
Query

A new query based on the current one, but with the specified start position.
Remarks

This call replaces any previously specified start position in the query.

StartAt(DocumentSnapshot)

public Query StartAt(DocumentSnapshot snapshot)

Creates and returns a new query that starts at the document snapshot provided fields relative to the order of the query.

Parameter
Name Description
snapshot DocumentSnapshot

The snapshot of the document to start at. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the specified start position.
Remarks

This call replaces any previously specified start position in the query.

StartAt(params object[])

public Query StartAt(params 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. Must not be null or empty, or have more values than query has orderings.
Returns
Type Description
Query

A new query based on the current one, but with the specified start position.
Remarks

This call replaces any previously specified start position in the query.

StreamAsync(CancellationToken)

public IAsyncEnumerable<DocumentSnapshot> StreamAsync(CancellationToken cancellationToken = default)

Returns an asynchronous sequence of snapshots matching the query.

Parameter
Name Description
cancellationToken CancellationToken

The cancellation token to apply to the streaming operation. Note that even if this is None, a cancellation token can still be applied when iterating over the stream, by passing it into GetAsyncEnumerator(CancellationToken). If a cancellation token is passed both to this method and GetAsyncEnumerator, then cancelling either of the tokens will result in the operation being cancelled.
Returns
Type Description
IAsyncEnumerableDocumentSnapshot

An asynchronous sequence of document snapshots matching the query.
Remarks

Each time you iterate over the sequence, a new query will be performed.

Where(Filter)

public Query Where(Filter filter)

Add the given filter to this query.

Parameter
Name Description
filter Filter

filter to be applied on query, must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereArrayContains(FieldPath, object)

public Query WhereArrayContains(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be an array containing value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to check in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereArrayContains(string, object)

public Query WhereArrayContains(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be an array containing value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to check in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereArrayContainsAny(FieldPath, IEnumerable)

public Query WhereArrayContainsAny(FieldPath fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is an array containing at least one value in values.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereArrayContainsAny(string, IEnumerable)

public Query WhereArrayContainsAny(string fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is an array containing at least one value in values.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereEqualTo(FieldPath, object)

public Query WhereEqualTo(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be equal to value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereEqualTo(string, object)

public Query WhereEqualTo(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be equal to value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereGreaterThan(FieldPath, object)

public Query WhereGreaterThan(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be greater than value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereGreaterThan(string, object)

public Query WhereGreaterThan(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be greater than value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereGreaterThanOrEqualTo(FieldPath, object)

public Query WhereGreaterThanOrEqualTo(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be greater than or equal to value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereGreaterThanOrEqualTo(string, object)

public Query WhereGreaterThanOrEqualTo(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be greater than or equal to value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereIn(FieldPath, IEnumerable)

public Query WhereIn(FieldPath fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is one of the values in values.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereIn(string, IEnumerable)

public Query WhereIn(string fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is one of the values in values.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereLessThan(FieldPath, object)

public Query WhereLessThan(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be less than value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereLessThan(string, object)

public Query WhereLessThan(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be less than value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereLessThanOrEqualTo(FieldPath, object)

public Query WhereLessThanOrEqualTo(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be less than or equal to value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereLessThanOrEqualTo(string, object)

public Query WhereLessThanOrEqualTo(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must be less than or equal to value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereNotEqualTo(FieldPath, object)

public Query WhereNotEqualTo(FieldPath fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must not be equal to value.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereNotEqualTo(string, object)

public Query WhereNotEqualTo(string fieldPath, object value)

Returns a query with a filter specifying that the value in fieldPath must not be equal to value.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
value object

The value to compare in the filter.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereNotIn(FieldPath, IEnumerable)

public Query WhereNotIn(FieldPath fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is not one of the values in values.

Parameters
Name Description
fieldPath FieldPath

The field path to filter on. Must not be null.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.

WhereNotIn(string, IEnumerable)

public Query WhereNotIn(string fieldPath, IEnumerable values)

Returns a query with a filter specifying that fieldPath must be a field present in the document, with a value which is not one of the values in values.

Parameters
Name Description
fieldPath string

The dot-separated field path to filter on. Must not be null or empty.
values IEnumerable

The values to compare in the filter. Must not be null.
Returns
Type Description
Query

A new query based on the current one, but with the additional specified filter applied.
Remarks

This call adds additional filters to any previously-specified ones.