Aggregations

class google.cloud.datastore.aggregation.AggregationQuery(client, query)

Bases: object

An Aggregation query against the Cloud Datastore.

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

add_aggregation(aggregation)

Adds an aggregation operation to the nested query

  • Parameters

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

add_aggregations(aggregations)

Adds a list of aggregations to the nested query :type aggregations: list :param aggregations: a list of aggregation operations

count(alias=None)

Adds a count over the nested query

  • Parameters

    alias (str) – (Optional) The alias for the count

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:

>>> 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
<google.cloud.datastore.aggregation.AggregationResultIterator object at ...>

  • Parameters

    • client (google.cloud.datastore.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.

  • Return type

    AggregationIterator

  • Returns

    The iterator for the aggregation query.

property namespace()

The nested query’s namespace

  • Return type

    str or None

  • Returns

    the namespace assigned to this query

property project()

Get the project for this AggregationQuery.

  • Return type

    str

  • Returns

    The project for the query.

class google.cloud.datastore.aggregation.AggregationResult(alias, value)

Bases: object

A class representing result from Aggregation Query

  • Parameters

    • alias (str) – The alias for the aggregation.

    • value (int) – The resulting value from the aggregation.

class google.cloud.datastore.aggregation.AggregationResultIterator(aggregation_query, client, limit=None, eventual=False, retry=None, timeout=None, read_time=None)

Bases: google.api_core.page_iterator.Iterator

Represent the state of a given execution of a Query.

  • Parameters

    • aggregation_query (AggregationQuery) – AggregationQuery object holding permanent configuration (i.e. things that don’t change on with each page in a results set).

    • client (Client) – The client used to make a request.

    • 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) Runs the query with read time consistency. Cannot be used with eventual consistency or inside a transaction, otherwise will raise ValueError. This feature is in private preview.

class google.cloud.datastore.aggregation.BaseAggregation()

Bases: abc.ABC

Base class representing an Aggregation operation in Datastore

class google.cloud.datastore.aggregation.CountAggregation(alias=None)

Bases: google.cloud.datastore.aggregation.BaseAggregation

Representation of a “Count” aggregation query.

  • Parameters

    • alias (str) – The alias for the aggregation.

    • value (int) – The resulting value from the aggregation.