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/v1/{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)

执行给定时间戳的查询。

此时间戳必须是过去一小时内的微秒级精确时间戳；如果启用了时间点恢复，也可以是过去 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 和当前 AggregationResult 之间不会发生变化。

如果查询未返回任何结果，则不会发送包含 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

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

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 结果的一系列汇总。

需要：

  • 每个查询至少有 1 个汇总，最多 5 个。
联合字段 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)

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

这提供了一种方式来设定要扫描的文档数量上限，从而限制延迟时间和费用。

未指定为无限制。

简要示例：

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

需要：

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

总和

所请求字段的值的总和。

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

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

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

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

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

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

object (FieldReference)

要汇总的字段。

Avg

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

  • 系统只会汇总数值。系统会跳过包括 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" }。