Class AggregationQuery (2.21.0) 

AggregationQuery(client, query, explain_options=None)

An Aggregation query against the Cloud Datastore.

This class serves as an abstraction for creating aggregations over query in the Cloud Datastore.

Parameters
Name Description
client Client

The client used to connect to Datastore.
query Query

The query used for aggregations.
explain_options ExplainOptions

(Optional) Options to enable query profiling for this query. When set, explain_metrics will be available on the iterator returned by query.fetch(). If not passed, will use value from given query.

Properties

namespace

The nested query's namespace

Returns
Type Description
str or None the namespace assigned to this query

project

Get the project for this AggregationQuery.

Returns
Type Description
str The project for the query.

Methods

add_aggregation

add_aggregation(aggregation)

Adds an aggregation operation to the nested query

Parameter
Name Description
aggregation BaseAggregation

An aggregation operation, e.g. a CountAggregation

add_aggregations

add_aggregations(aggregations)

Adds a list of aggregations to the nested query

Parameter
Name Description
aggregations list

a list of aggregation operations

avg

avg(property_ref, alias=None)

Adds a avg over the nested query

Parameter
Name Description
property_ref str

The property_ref for the sum

count

count(alias=None)

Adds a count over the nested query

Parameter
Name Description
alias str

(Optional) The alias for the count

fetch

fetch(
    client=None, limit=None, eventual=False, retry=None, timeout=None, read_time=None
)

Execute the Aggregation Query; return an iterator for the aggregation results.

For example:

.. testsetup:: aggregation-query-fetch

import uuid

from google.cloud import datastore

unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))

.. doctest:: aggregation-query-fetch

>>> andy = datastore.Entity(client.key('Person', 1234))
>>> andy['name'] = 'Andy'
>>> sally = datastore.Entity(client.key('Person', 2345))
>>> sally['name'] = 'Sally'
>>> bobby = datastore.Entity(client.key('Person', 3456))
>>> bobby['name'] = 'Bobby'
>>> client.put_multi([andy, sally, bobby])
>>> query = client.query(kind='Andy')
>>> aggregation_query = client.aggregation_query(query)
>>> result = aggregation_query.count(alias="total").fetch(limit=5)
>>> result
<<xref uid="google.cloud.datastore.aggregation.AggregationResultIterator">google.cloud.datastore.aggregation.AggregationResultIterator</xref> object at ...>

.. testcleanup:: aggregation-query-fetch

client.delete(andy.key)
Parameters
Name Description
client Client

(Optional) client used to connect to datastore. If not supplied, uses the query's value.
eventual bool

(Optional) Defaults to strongly consistent (False). Setting True will use eventual consistency, but cannot be used inside a transaction or with read_time, otherwise will raise ValueError.
retry google.api_core.retry.Retry

A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.
timeout float

Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.
read_time datetime

(Optional) use read_time read consistency, cannot be used inside a transaction or with eventual consistency, or will raise ValueError.
Returns
Type Description
AggregationIterator The iterator for the aggregation query.

sum

sum(property_ref, alias=None)

Adds a sum over the nested query

Parameter
Name Description
property_ref str

The property_ref for the sum