Method: projects.databases.documents.runAggregationQuery

Runs an aggregation query.

Rather than producing Document results like Firestore.RunQuery, this API allows running an aggregation to produce a series of AggregationResult server-side.

High-Level Example:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

HTTP request

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The parent resource name. In the format: projects/{projectId}/databases/{databaseId}/documents or projects/{projectId}/databases/{databaseId}/documents/{document_path}. For example: projects/my-project/databases/my-database/documents or projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Request body

The request body contains data with the following structure:

JSON representation 
{

  // Union field query_type can be only one of the following:
  "structuredAggregationQuery": {
    object (StructuredAggregationQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
Fields
Union field query_type. The query to run. query_type can be only one of the following:
structuredAggregationQuery

object (StructuredAggregationQuery)

An aggregation query.
Union field consistency_selector. The consistency mode for the query, defaults to strong consistency. consistency_selector can be only one of the following:
transaction

string (bytes format)

Run the aggregation within an already active transaction.

The value here is the opaque transaction ID to execute the query in.

A base64-encoded string.
newTransaction

object (TransactionOptions)

Starts a new transaction as part of the query, defaulting to read-only.

The new transaction ID will be returned as the first response in the stream.
readTime

string (Timestamp format)

Executes the query at the given timestamp.

Requires:

  • Cannot be more than 270 seconds in the past.

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".

Response body

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

The response for Firestore.RunAggregationQuery.

JSON representation 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string
}
Fields
result

object (AggregationResult)

A single aggregation result.

Not present when reporting partial progress.
transaction

string (bytes format)

The transaction that was started as part of this request.

Only present on the first response when the request requested to start a new transaction.

A base64-encoded string.
readTime

string (Timestamp format)

The time at which the aggregate value is valid for.

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".

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.

StructuredAggregationQuery

Firestore query for running an aggregation over a StructuredQuery.

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

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // 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 structuredQuery.

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:
structuredQuery

object (StructuredQuery)

Nested structured query.

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 field to store the result of the aggregation into.

If not provided, Firestore will pick a default name following the format field_<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 field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT_UP_TO(4) AS field_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.

Count

Count of documents that match the query.

The COUNT(*) aggregation function operates on the entire document 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 documents to count.

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

Unspecified is interpreted as no bound.

High-Level Example:

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

Requires:

  • Must be greater than zero when present.

AggregationResult

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

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

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

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

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

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" }.