Console
    Contact Us Start free

    Method: projects.runAggregationQuery

    Runs an aggregation query.

    HTTP request

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

    The URL uses gRPC Transcoding syntax.

    Path parameters

    Parameters
    project Id

    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 
     { 
 "databaseId" 
 : 
 string 
 , 
 "partitionId" 
 : 
 { 
 object (  PartitionId 
 
) 
 } 
 , 
 "readOptions" 
 : 
 { 
 object (  ReadOptions 
 
) 
 } 
 , 
 "explainOptions" 
 : 
 { 
 object (  ExplainOptions 
 
) 
 } 
 , 
 // 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
    database Id

    string

    The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

    partition Id

    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.

    read Options

    object ( ReadOptions )

    The options for this query.

    explain Options

    object ( ExplainOptions )

    Optional. Explain options for the query. If set, additional query statistics will be returned. If not, only query results will be returned.

    Union field query_type . The type of query. query_type can be only one of the following:
    aggregation Query

    object ( AggregationQuery )

    The query to run.

    gql Query

    object ( GqlQuery )

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

    Response body

    The response for Datastore.RunAggregationQuery .

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

    JSON representation 
     { 
 "batch" 
 : 
 { 
 object (  AggregationResultBatch 
 
) 
 } 
 , 
 "query" 
 : 
 { 
 object (  AggregationQuery 
 
) 
 } 
 , 
 "transaction" 
 : 
 string 
 , 
 "explainMetrics" 
 : 
 { 
 object (  ExplainMetrics 
 
) 
 } 
 }
    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.
    transaction

    string ( bytes format)

    The identifier of the transaction that was started as part of this projects.runAggregationQuery request.

    Set only when ReadOptions.new_transaction was set in RunAggregationQueryRequest.read_options .

    A base64-encoded string.
    explain Metrics

    object ( ExplainMetrics )

    Query explain metrics. This is only present when the RunAggregationQueryRequest.explain_options is provided, and it is sent only once with the last response in the stream.

    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:
    nested Query

    object ( Query )

    Nested query for aggregation

    Aggregation

    Defines an aggregation that produces a single result.

    JSON representation 
     { 
 "alias" 
 : 
 string 
 , 
 // Union field operator 
can be only one of the following: 
 "count" 
 : 
 { 
 object (  Count 
 
) 
 } 
 , 
 "sum" 
 : 
 { 
 object (  Sum 
 
) 
 } 
 , 
 "avg" 
 : 
 { 
 object (  Avg 
 
) 
 } 
 // 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(*)
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(*) AS property_2
OVER (
  ...
);

    Requires:

    Union field operator . The type of aggregation to perform, required. operator can be only one of the following:
    count

    object ( Count )

    Count aggregator.

    sum

    object ( Sum )

    Sum aggregator.

    avg

    object ( Avg )

    Average 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
    up To

    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.

    Sum

    Sum of the values of the requested property.

    • Only numeric values will be aggregated. All non-numeric values including NULL are skipped.

    • If the aggregated values contain NaN , returns NaN . Infinity math follows IEEE-754 standards.

    • If the aggregated value set is empty, returns 0.

    • Returns a 64-bit integer if all aggregated numbers are integers and the sum result does not overflow. Otherwise, the result is returned as a double. Note that even if all the aggregated values are integers, the result is returned as a double if it cannot fit within a 64-bit signed integer. When this occurs, the returned value will lose precision.

    • When underflow occurs, floating-point aggregation is non-deterministic. This means that running the same query repeatedly without any changes to the underlying values could produce slightly different results each time. In those cases, values should be stored as integers over floating-point numbers.

    JSON representation 
     { 
 "property" 
 : 
 { 
 object (  PropertyReference 
 
) 
 } 
 }
    Fields
    property

    object ( PropertyReference )

    The property to aggregate on.

    Avg

    Average of the values of the requested property.

    • Only numeric values will be aggregated. All non-numeric values including NULL are skipped.

    • If the aggregated values contain NaN , returns NaN . Infinity math follows IEEE-754 standards.

    • If the aggregated value set is empty, returns NULL .

    • Always returns the result as a double.

    JSON representation 
     { 
 "property" 
 : 
 { 
 object (  PropertyReference 
 
) 
 } 
 }
    Fields
    property

    object ( PropertyReference )

    The property to aggregate on.

    AggregationResultBatch

    A batch of aggregation results produced by an aggregation query.

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

    object ( AggregationResult )

    The aggregation results for this batch.
    more Results

    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 .
    read Time

    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.

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted.Examples: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30" .

    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
    aggregate Properties

    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" } .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: