Method: projects.runAggregationQuery

Runs an aggregation query.

HTTP request

POST https://datastore.googleapis.com/v1beta3/projects/{projectId}:runAggregationQuery

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
projectId

string

Required. The ID of the project against which to make the request.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "partitionId": {
    object (PartitionId)
  },
  "readOptions": {
    object (ReadOptions)
  },

  // Union field query_type can be only one of the following:
  "aggregationQuery": {
    object (AggregationQuery)
  },
  "gqlQuery": {
    object (GqlQuery)
  }
  // End of list of possible types for union field query_type.
}
Fields
partitionId

object (PartitionId)

Entities are partitioned into subsets, identified by a partition ID. Queries are scoped to a single partition. This partition ID is normalized with the standard default context partition ID.
readOptions

object (ReadOptions)

The options for this query.
Union field query_type. The type of query. query_type can be only one of the following:
aggregationQuery

object (AggregationQuery)

The query to run.
gqlQuery

object (GqlQuery)

The GQL query to run. This query must be an aggregation query.

Response body

If successful, the response body contains data with the following structure:

The response for Datastore.RunAggregationQuery.

JSON representation 
{
  "batch": {
    object (AggregationResultBatch)
  },
  "query": {
    object (AggregationQuery)
  }
}
Fields
batch

object (AggregationResultBatch)

A batch of aggregation results. Always present.
query

object (AggregationQuery)

The parsed form of the GqlQuery from the request, if it was set.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

AggregationQuery

Datastore query for running an aggregation over a Query.

JSON representation 
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // Union field query_type can be only one of the following:
  "nestedQuery": {
    object (Query)
  }
  // End of list of possible types for union field query_type.
}
Fields
aggregations[]

object (Aggregation)

Optional. Series of aggregations to apply over the results of the nestedQuery.

Requires:

  • A minimum of one and maximum of five aggregations per query.
Union field query_type. The base query to aggregate over. query_type can be only one of the following:
nestedQuery

object (Query)

Nested query for aggregation

Aggregation

Defines a aggregation that produces a single result.

JSON representation 
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  }
  // End of list of possible types for union field operator.
}
Fields
alias

string

Optional. Optional name of the property to store the result of the aggregation.

If not provided, Datastore will pick a default name following the format property_<incremental_id++>. For example:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT_UP_TO(4)
OVER (
  ...
);

becomes:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS property_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT_UP_TO(4) AS property_2
OVER (
  ...
);

Requires:

  • Must be unique across all aggregation aliases.
  • Conform to entity property name limitations.
Union field operator. The type of aggregation to perform, required. operator can be only one of the following:
count

object (Count)

Count aggregator.

Count

Count of entities that match the query.

The COUNT(*) aggregation function operates on the entire entity so it does not require a field reference.

JSON representation 
{
  "upTo": string
}
Fields
upTo

string (Int64Value format)

Optional. Optional constraint on the maximum number of entities to count.

This provides a way to set an upper bound on the number of entities to scan, limiting latency and cost.

Unspecified is interpreted as no bound.

If a zero value is provided, a count result of zero should always be expected.

High-Level Example:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

Requires:

  • Must be non-negative when present.

AggregationResultBatch

A batch of aggregation results produced by an aggregation query.

JSON representation 
{
  "aggregationResults": [
    {
      object (AggregationResult)
    }
  ],
  "moreResults": enum (MoreResultsType),
  "readTime": string
}
Fields
aggregationResults[]

object (AggregationResult)

The aggregation results for this batch.
moreResults

enum (MoreResultsType)

The state of the query after the current batch. Only COUNT(*) aggregations are supported in the initial launch. Therefore, expected result type is limited to NO_MORE_RESULTS.
readTime

string (Timestamp format)

Read timestamp this batch was returned from.

In a single transaction, subsequent query result batches for the same query can have a greater timestamp. Each batch's read timestamp is valid for all preceding batches.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

AggregationResult

The result of a single bucket from a Datastore aggregation query.

The keys of aggregateProperties are the same for all results in an aggregation query, unlike entity queries which can have different fields present for each result.

JSON representation 
{
  "aggregateProperties": {
    string: {
      object (Value)
    },
    ...
  }
}
Fields
aggregateProperties

map (key: string, value: object (Value))

The result of the aggregation functions, ex: COUNT(*) AS total_entities.

The key is the alias assigned to the aggregation function on input and the size of this map equals the number of aggregation functions in the query.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.