Method: projects.databases.documents.runAggregationQuery

运行聚合查询。

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

简要示例:

-- 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}/documentsprojects/{projectId}/databases/{databaseId}/documents/{document_path}。例如:projects/my-project/databases/my-database/documentsprojects/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" }