运行聚合查询。
此 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 |
必需。父级资源名称。格式为: |
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "explainOptions": { object ( |
字段 | |
---|---|
explainOptions |
可选。说明查询的选项。如果设置了此字段,则会返回其他查询统计信息。否则,将仅返回查询结果。 |
联合字段 query_type 。要运行的查询。query_type 只能是下列其中一项: |
|
structuredAggregationQuery |
聚合查询。 |
联合字段 consistency_selector 。查询的一致性模式默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
在已活跃的事务中运行汇总。 此处的值是要执行查询的不透明事务 ID。 使用 base64 编码的字符串。 |
newTransaction |
在查询中启动新事务,默认为只读。 新的交易 ID 将作为数据流中的第一个响应返回。 |
readTime |
执行给定时间戳的查询。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式的时间戳,采用纳秒级精度,最多包含九个小数位。示例: |
响应正文
Firestore.RunAggregationQuery
的响应。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{ "result": { object ( |
字段 | |
---|---|
result |
单个汇总结果。 报告部分进度时不存在。 |
transaction |
作为此请求的一部分启动的事务。 仅在请求请求启动新事务时出现在第一个响应中。 使用 base64 编码的字符串。 |
readTime |
计算汇总结果的时间。此值始终是单调递增的;在这种情况下,结果流中的上一个 AggregationResult 在其 如果查询未返回任何结果,则不会发送包含 采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式的时间戳,采用纳秒级精度,最多包含九个小数位。示例: |
explainMetrics |
查询说明指标。此属性仅在提供了 |
授权范围
需要以下 OAuth 范围之一:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
如需了解详情,请参阅身份验证概览。
StructuredAggregationQuery
用于对 StructuredQuery
运行聚合的 Firestore 查询。
JSON 表示法 |
---|
{ "aggregations": [ { object ( |
字段 | |
---|---|
aggregations[] |
可选。要应用于 需要:
|
联合字段 query_type 。要汇总的基本查询。query_type 只能是下列其中一项: |
|
structuredQuery |
嵌套结构化查询。 |
汇总
定义可生成单个结果的聚合。
JSON 表示法 |
---|
{ "alias": string, // Union field |
字段 | |
---|---|
alias |
可选。用于存储汇总结果的字段的可选名称。 如果未提供,Firestore 将选择遵循
变为:
需要:
|
联合字段 operator 。要执行的汇总类型,必填。operator 只能是下列其中一项: |
|
count |
计数聚合器。 |
sum |
求和聚合器。 |
avg |
一般的集合商家。 |
计数
与查询匹配的文档数。
COUNT(*)
聚合函数会对整个文档执行操作,因此不需要字段引用。
JSON 表示法 |
---|
{ "upTo": string } |
字段 | |
---|---|
upTo |
可选。(可选)对要统计的文档数量上限的限制。 这提供了一种方式来设定要扫描的文档数量上限,从而限制延迟时间和费用。 未指定为无限制。 简要示例:
需要:
|
总和
所请求字段的值的总和。
系统只会汇总数值。系统会跳过包括
NULL
在内的所有非数字值。如果聚合值包含
NaN
,则返回NaN
。无穷大数学遵循 IEEE-754 标准。如果汇总值集为空,则返回 0。
如果所有汇总数据都是整数,并且求和结果不溢出,则返回 64 位整数。否则,返回的结果为双精度型。请注意,即使所有聚合值都是整数,如果结果无法放入 64 位的带符号整数,也会以双精度形式返回。如果发生这种情况,返回的值会失去精度。
发生下溢时,浮点聚合是不确定的。这意味着,如果在不更改基础值的情况下重复运行同一查询,每次的结果可能略有不同。在此类情况下,值应存储为整数而非浮点数。
JSON 表示法 |
---|
{
"field": {
object ( |
字段 | |
---|---|
field |
要汇总的字段。 |
Avg
所请求字段的值的平均值。
系统只会汇总数值。系统会跳过包括
NULL
在内的所有非数字值。如果聚合值包含
NaN
,则返回NaN
。无穷大数学遵循 IEEE-754 标准。如果汇总值集为空,则返回
NULL
。始终以双精度类型返回结果。
JSON 表示法 |
---|
{
"field": {
object ( |
字段 | |
---|---|
field |
要汇总的字段。 |
AggregationResult
Firestore 聚合查询中单个存储分区的结果。
与文档查询不同,文档查询可以为每个结果显示不同的字段,聚合查询中所有结果的 aggregateFields
键都是相同的。
JSON 表示法 |
---|
{
"aggregateFields": {
string: {
object ( |
字段 | |
---|---|
aggregateFields |
聚合函数的结果,例如: 键是分配给输入时聚合函数的 包含一系列 |