汇总函数

聚合

所有聚合函数都可以在 aggregate(...) 阶段用作顶级表达式。

名称 说明
COUNT 返回文档数量。
COUNT_IF 返回表达式求值结果为 TRUE 的文档数量
COUNT_DISTINCT 返回唯一非 NULL 值的数量
SUM 返回所有 NUMERIC 值的总和
AVERAGE 返回所有 NUMERIC 值的平均值
MINIMUM 返回最小的非 NULL 值
MAXIMUM 返回最大的非 NULL 值
FIRST 返回第一个文档的 expression 值。
LAST 返回最后一个文档的 expression 值。
ARRAY_AGG 返回一个包含所有输入值的数组。
ARRAY_AGG_DISTINCT 返回由所有不重复输入值构成的数组。

COUNT

语法：

count() -> INT64
count(expression: ANY) -> INT64

说明：

返回在上一阶段中，expression 的求值结果为任意非 NULL 值的文档数量。如果未提供 expression，则返回上一个阶段的文档总数。

Web

// Total number of books in the collection
const countOfAll = await execute(db.pipeline()
  .collection("books")
  .aggregate(countAll().as("count"))
);

// Number of books with nonnull `ratings` field
const countField = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("ratings").count().as("count"))
);
test.firestore.js
Swift
// Total number of books in the collection
let countAll = try await db.pipeline()
  .collection("books")
  .aggregate([CountAll().as("count")])
  .execute()

// Number of books with nonnull `ratings` field
let countField = try await db.pipeline()
  .collection("books")
  .aggregate([Field("ratings").count().as("count")])
  .execute()
PipelineSnippets.swift

Kotlin

// Total number of books in the collection
val countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute()

// Number of books with nonnull `ratings` field
val countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute()
DocSnippets.kt

Java

// Total number of books in the collection
Task<Pipeline.Snapshot> countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute();

// Number of books with nonnull `ratings` field
Task<Pipeline.Snapshot> countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Count

# Total number of books in the collection
count_all = (
    client.pipeline().collection("books").aggregate(Count().as_("count")).execute()
)

# Number of books with nonnull `ratings` field
count_field = (
    client.pipeline()
    .collection("books")
    .aggregate(Count("ratings").as_("count"))
    .execute()
)
firestore_pipelines.py

COUNT_IF

语法：

count_if(expression: BOOLEAN) -> INT64

说明：

返回上一个阶段中 expression 的计算结果为 TRUE 的文档数量。

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(
    field("rating").greaterThan(4).countIf().as("filteredCount")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([
    AggregateFunction("count_if", [Field("rating").greaterThan(4)]).as("filteredCount")
  ])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("rating").greater_than(4).count_if().as_("filteredCount"))
    .execute()
)
firestore_pipelines.py

COUNT_DISTINCT

语法：

count_distinct(expression: ANY) -> INT64

说明：

返回 expression 中唯一且非 NULL、非 ABSENT 的值的数量。

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("author").countDistinct().as("unique_authors"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([AggregateFunction("count_distinct", [Field("author")]).as("unique_authors")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("author").count_distinct().as_("unique_authors"))
    .execute()
)
firestore_pipelines.py

SUM

语法：

sum(expression: ANY) -> NUMBER

说明：

返回所有数值的总和，忽略非数值。如果任何值是 NaN，则返回 NaN。

输出类型通常与最宽的输入类型一致，但以下情况除外：

  • 如果 INTEGER 无法表示为 INTEGER，则会将其转换为 DOUBLE。

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").sum().as("totalPopulation"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").sum().as("totalPopulation")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").sum().as_("totalPopulation"))
    .execute()
)
firestore_pipelines.py

AVERAGE

语法：

average(expression: ANY) -> FLOAT64

说明：

返回所有数值的平均值，忽略非数值。如果任何值都是 NaN，则计算结果为 NaN；如果没有汇总任何数值，则计算结果为 NULL。

输出将具有与输入类型相同的类型，但以下情况除外：

  • 如果 INTEGER 无法表示为 INTEGER，则会将其转换为 DOUBLE。

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").average().as("averagePopulation"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").average().as("averagePopulation")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").average().as_("averagePopulation"))
    .execute()
)
firestore_pipelines.py

MINIMUM

语法：

minimum(expression: ANY) -> ANY

说明：

返回在每个文档上求值时，expression 的最小非 NULL 且非缺失值。

如果不存在非 NULL 且非缺失的值，则返回 NULL。这也适用于未包含任何文档的情况。

如果存在多个相等的最小值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").minimum().as("minimumPrice")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").minimum().as_("minimumPrice"))
    .execute()
)
firestore_pipelines.py

MAXIMUM

语法：

maximum(expression: ANY) -> ANY

说明：

返回在每个文档上求值时，expression 的最大非 NULL 且非缺失值。

如果不存在非 NULL 且非缺失的值，则返回 NULL。这也适用于未包含任何文档的情况。

如果存在多个相等的最大值，则可以返回其中任意一个。值类型的排序遵循文档所定义的排序。

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").maximum().as("maximumPrice")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").maximum().as_("maximumPrice"))
    .execute()
)
firestore_pipelines.py

FIRST

语法：

first(expression: ANY) -> ANY

说明：

返回第一个返回的文档的 expression 值。

LAST

语法：

last(expression: ANY) -> ANY

说明：

返回最后一个返回的文档的 expression 值。

ARRAY_AGG

语法：

array_agg(expression: ANY) -> ARRAY<ANY>

说明：

返回一个数组，其中包含对每个文档求值时 expression 的所有值。

如果表达式解析为缺失值，则会将其转换为 NULL。

输出数组中元素的顺序不稳定，请勿依赖此顺序。

ARRAY_AGG_DISTINCT

语法：

array_agg_distinct(expression: ANY) -> ARRAY<ANY>

说明：

返回一个数组，其中包含针对每个文档求值时 expression 的所有不同值。

如果表达式解析为缺失值，则会将其转换为 NULL。

输出数组中元素的顺序不稳定，请勿依赖此顺序。