Method: projects.databases.documents.runAggregationQuery

运行聚合查询。

此 API 允许运行聚合以在服务器端生成一系列 AggregationResult，而不是生成 Firestore.RunQuery 等 Document 结果。

简要示例：

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

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。父级资源名称。格式为 projects/{projectId}/databases/{databaseId}/documents 或 projects/{projectId}/databases/{databaseId}/documents/{document_path}。例如：projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // 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.
}
字段
explainOptions

object (ExplainOptions)

可选。解释查询的选项。如果设置，将返回其他查询统计信息。否则，系统只会返回查询结果。
联合字段 query_type。要运行的查询。query_type 只能是下列其中一项：
structuredAggregationQuery

object (StructuredAggregationQuery)

聚合查询。
联合字段 consistency_selector。查询的一致性模式默认为强一致性。consistency_selector 只能是下列其中一项：
transaction

string (bytes format)

在已处于活跃状态的事务中运行聚合。

此处的值是用于执行查询的不透明事务 ID。

使用 base64 编码的字符串。
newTransaction

object (TransactionOptions)

作为查询的一部分启动一个新事务，默认为只读。

新的交易 ID 将作为数据流中的第一个响应返回。
readTime

string (Timestamp format)

在给定的时间戳执行查询。

该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

响应正文

Firestore.RunAggregationQuery 的响应。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
字段
result

object (AggregationResult)

单个汇总结果。

报告部分进度时不会显示。
transaction

string (bytes format)

作为此请求的一部分启动的事务。

仅当请求请求启动新事务时，才出现在第一个响应中。

使用 base64 编码的字符串。
readTime

string (Timestamp format)

计算汇总结果的时间。该值始终是单调递增的；在这种情况下，结果流中的前一个 AggregationResult 保证在其 readTime 和此版本之间不发生变化。

如果查询未返回任何结果，系统将发送包含 readTime 但不返回 result 的响应，这表示查询的运行时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
explainMetrics

object (ExplainMetrics)

查询说明指标。仅当提供了 RunAggregationQueryRequest.explain_options 时，此字段才会显示，并且它仅随数据流中的最后一个响应发送一次。

授权范围

需要以下 OAuth 范围之一：

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

如需了解详情，请参阅身份验证概览。

StructuredAggregationQuery

Firestore 查询，用于对 StructuredQuery 运行聚合。

JSON 表示法 
{
  "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.
}
字段
aggregations[]

object (Aggregation)

可选。要对 structuredQuery 的结果应用的一系列聚合。

需要：

  • 每个查询最少包含五项汇总，最多五项。
联合字段 query_type。要汇总的基本查询。query_type 只能是下列其中一项：
structuredQuery

object (StructuredQuery)

嵌套的结构化查询。

聚合

定义可生成单个结果的聚合。

JSON 表示法 
{
  "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.
}
字段
alias

string

可选。用于存储聚合结果的字段的可选名称。

如果未提供，Firestore 将选择一个遵循 field_<incremental_id++> 格式的默认名称。例如：

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 (
  ...
);

会变为：

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(*) AS field_2
OVER (
  ...
);

需要：
联合字段 operator。要执行的汇总类型，必填。operator 只能是下列其中一项：
count

object (Count)

计数聚合器。
sum

object (Sum)

总和聚合器。
avg

object (Avg)

平均集合商家。

计数

与查询匹配的文档数。

COUNT(*) 聚合函数可对整个文档执行运算，因此它不需要字段引用。

JSON 表示法 
{
  "upTo": string
}
字段
upTo

string (Int64Value format)

可选。对要计数的文档数量上限的可选限制。

此方法可用于设置要扫描的文档数量的上限，以限制延迟时间和费用。

Unspecified 会被视为无限制。

简要示例：

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

需要：

  • 如果存在，必须大于零。

总和

所请求字段的值的总和。

  • 系统只会汇总数值。系统会跳过包括 NULL 在内的所有非数字值。

  • 如果汇总值包含 NaN，则返回 NaN。无穷大数学遵循 IEEE-754 标准。

  • 如果汇总值集为空，则返回 0。

  • 如果所有汇总数字均为整数，且求和结果没有溢出，则返回 64 位整数。否则，结果将作为双精度值返回。请注意，即使所有汇总值都是整数，如果无法放入 64 位带符号的整数，也会以双精度类型的值返回结果。如果发生这种情况，返回的值将失去精度。

  • 发生下溢时，浮点汇总是不确定的。这意味着，重复运行同一查询而不更改基础值，每次可能会产生略有不同的结果。在这些情况下，值应该存储为整数而不是浮点数。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  }
}
字段
field

object (FieldReference)

要汇总的字段。

平均

所请求字段的值的平均值。

  • 系统只会汇总数值。系统会跳过包括 NULL 在内的所有非数字值。

  • 如果汇总值包含 NaN，则返回 NaN。无穷大数学遵循 IEEE-754 标准。

  • 如果汇总值集为空，则返回 NULL。

  • 始终以双精度类型返回结果。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  }
}
字段
field

object (FieldReference)

要汇总的字段。

AggregationResult 类中的方法

Firestore 聚合查询返回单个存储分区的结果。

聚合查询中所有结果的 aggregateFields 键都是相同的，这与文档查询可以为每个结果显示不同的字段不同。

JSON 表示法 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
字段
aggregateFields

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

聚合函数的结果，例如：COUNT(*) AS total_docs。

键是针对输入分配给聚合函数的 alias，此映射的大小等于查询中聚合函数的数量。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。