As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Aggregation

Classes for representing aggregation queries for the Google Cloud Firestore API.

A AggregationQuery can be created directly from a Collection and that can be a more common way to create an aggregation query than direct usage of the constructor.

class google.cloud.firestore_v1.aggregation.AggregationQuery(nested_query)[source]

Bases: google.cloud.firestore_v1.base_aggregation.BaseAggregationQuery

Represents an aggregation query to the Firestore API.

get(transaction=None, retry: Union[retries.Retry, None, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE, timeout: float | None = None, *, explain_options: Optional[ExplainOptions] = None) → QueryResultsList[AggregationResult][source]

Runs the aggregation query.

This sends a RunAggregationQuery RPC and returns a list of aggregation results in the stream of RunAggregationQueryResponse messages.

Parameters

  • transaction – (Optional[Transaction]): An existing transaction that this query will run in. If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

  • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (float) – The timeout for this request. Defaults to a system-specified value.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

The aggregation query results.

Return type

QueryResultsList[AggregationResult]

stream(transaction: Optional['transaction.Transaction'] = None, retry: Union[retries.Retry, None, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None, *, explain_options: Optional[ExplainOptions] = None) → StreamGenerator[List[AggregationResult]][source]

Runs the aggregation query.

This sends a RunAggregationQuery RPC and then returns a generator which consumes each document returned in the stream of RunAggregationQueryResponse messages.

If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

Parameters

  • transaction – (Optional[Transaction]): An existing transaction that this query will run in.

  • retry (Optional[google.api_core.retry.Retry]) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (Optinal[float]) – The timeout for this request. Defaults

  • value. (to a system-specified) –

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

A generator of the query results.

Return type

StreamGenerator[List[AggregationResult]]

Classes for representing aggregation queries for the Google Cloud Firestore API.

A AggregationQuery can be created directly from a Collection and that can be a more common way to create an aggregation query than direct usage of the constructor.

class google.cloud.firestore_v1.base_aggregation.AggregationResult(alias: str, value: float, read_time=None)[source]

Bases: object

A class representing result from Aggregation Query :type alias: str :param alias: The alias for the aggregation. :type value: int :param value: The resulting value from the aggregation. :type read_time: :param value: The resulting read_time

class google.cloud.firestore_v1.base_aggregation.AvgAggregation(field_ref: str | google.cloud.firestore_v1.field_path.FieldPath, alias: Optional[str] = None)[source]

Bases: google.cloud.firestore_v1.base_aggregation.BaseAggregation

class google.cloud.firestore_v1.base_aggregation.BaseAggregation(alias: Optional[str] = None)[source]

Bases: abc.ABC

class google.cloud.firestore_v1.base_aggregation.BaseAggregationQuery(nested_query, alias: Optional[str] = None)[source]

Bases: abc.ABC

Represents an aggregation query to the Firestore API.

add_aggregation(aggregation: google.cloud.firestore_v1.base_aggregation.BaseAggregation) → None[source]

Adds an aggregation operation to the nested query

Parameters

aggregation (google.cloud.firestore_v1.aggregation.BaseAggregation) – An aggregation operation, e.g. a CountAggregation

add_aggregations(aggregations: List[google.cloud.firestore_v1.base_aggregation.BaseAggregation]) → None[source]

Adds a list of aggregations to the nested query

Parameters

aggregations (list) – a list of aggregation operations

avg(field_ref: str | google.cloud.firestore_v1.field_path.FieldPath, alias: Optional[str] = None)[source]

Adds an avg over the nested query

count(alias: Optional[str] = None)[source]

Adds a count over the nested query

abstract get(transaction=None, retry: Union[retries.Retry, None, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE, timeout: float | None = None, *, explain_options: Optional[ExplainOptions] = None) → QueryResultsList[AggregationResult] | Coroutine[Any, Any, List[List[AggregationResult]]][source]

Runs the aggregation query.

This sends a RunAggregationQuery RPC and returns a list of aggregation results in the stream of RunAggregationQueryResponse messages.

Parameters

  • transaction – (Optional[Transaction]): An existing transaction that this query will run in. If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

  • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (float) – The timeout for this request. Defaults to a system-specified value.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

The aggregation query results.

Return type

(QueryResultsList[List[AggregationResult]] | Coroutine[Any, Any, List[List[AggregationResult]]])

abstract stream(transaction: Optional[transaction.Transaction] = None, retry: Union[retries.Retry, None, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None, *, explain_options: Optional[ExplainOptions] = None) → StreamGenerator[List[AggregationResult]] | AsyncStreamGenerator[List[AggregationResult]][source]

Runs the aggregation query.

This sends a``RunAggregationQuery`` RPC and returns a generator in the stream of RunAggregationQueryResponse messages.

Parameters

  • transaction – (Optional[Transaction]): An existing transaction that this query will run in.

  • retry (Optional[google.api_core.retry.Retry]) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (Optinal[float]) – The timeout for this request. Defaults to a system-specified value.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

A generator of the query results.

Return type

StreamGenerator[List[AggregationResult]] | AsyncStreamGenerator[List[AggregationResult]]

sum(field_ref: str | google.cloud.firestore_v1.field_path.FieldPath, alias: Optional[str] = None)[source]

Adds a sum over the nested query

class google.cloud.firestore_v1.base_aggregation.CountAggregation(alias: Optional[str] = None)[source]

Bases: google.cloud.firestore_v1.base_aggregation.BaseAggregation

class google.cloud.firestore_v1.base_aggregation.SumAggregation(field_ref: str | google.cloud.firestore_v1.field_path.FieldPath, alias: Optional[str] = None)[source]

Bases: google.cloud.firestore_v1.base_aggregation.BaseAggregation

Classes for representing Async aggregation queries for the Google Cloud Firestore API.

A AsyncAggregationQuery can be created directly from a AsyncCollection and that can be a more common way to create an aggregation query than direct usage of the constructor.

class google.cloud.firestore_v1.async_aggregation.AsyncAggregationQuery(nested_query)[source]

Bases: google.cloud.firestore_v1.base_aggregation.BaseAggregationQuery

Represents an aggregation query to the Firestore API.

async get(transaction=None, retry: Union[retries.AsyncRetry, None, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE, timeout: float | None = None, *, explain_options: Optional[ExplainOptions] = None) → QueryResultsList[List[AggregationResult]][source]

Runs the aggregation query.

This sends a RunAggregationQuery RPC and returns a list of aggregation results in the stream of RunAggregationQueryResponse messages.

Parameters

  • transaction – (Optional[Transaction]): An existing transaction that this query will run in. If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

  • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (float) – The timeout for this request. Defaults to a system-specified value.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

The aggregation query results.

Return type

QueryResultsList[List[AggregationResult]]

stream(transaction: Optional[transaction.Transaction] = None, retry: Optional[retries.AsyncRetry] = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None, *, explain_options: Optional[ExplainOptions] = None) → AsyncStreamGenerator[List[AggregationResult]][source]

Runs the aggregation query.

This sends a RunAggregationQuery RPC and then returns a generator which consumes each document returned in the stream of RunAggregationQueryResponse messages.

If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

Parameters

  • transaction (Optional[                Transaction]) – An existing transaction that the query will run in.

  • retry (Optional[google.api_core.retry.Retry]) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

  • timeout (Optional[float]) – The timeout for this request. Defaults to a system-specified value.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator.

Returns

A generator of the query results.

Return type

AsyncStreamGenerator[List[AggregationResult]]