Cloud Firestore Enterprise edition in Native mode is now available!Learn more.
Aggregate functions
Preview:Firestore in Native mode (with Pipeline operations) for Enterpriseedition is subject to the "Pre-GA Offerings Terms" in the GeneralService Terms section of theService SpecificTerms. You can process personaldata for this feature as outlined in theCloud Data Processing Addendum, subjectto the obligations and restrictions described in the agreement under which youaccess Google Cloud. Pre-GA features are available "as is" and might havelimited support. For more information, see thelaunch stagedescriptions.
Aggregate
All aggregate functions can be used as top-level expressions in theaggregate(...) stage.
| Name | Description |
COUNT | Returns the number of documents. |
COUNT_IF | Returns the count of documents where an expression evaluates toTRUE |
COUNT_DISTINCT | Returns the count of unique, nonNULL values |
SUM | Returns the sum of allNUMERIC values |
AVERAGE | Returns the average of allNUMERIC values |
MINIMUM | Returns the minimum nonNULL value |
MAXIMUM | Returns the maximum nonNULL value |
FIRST | Returns theexpression value for the first document. |
LAST | Returns theexpression value for the last document. |
ARRAY_AGG | Returns an array of all input values. |
ARRAY_AGG_DISTINCT | Returns an array of all distinct input values. |
COUNT
Syntax:
count() -> INT64count(expression: ANY) -> INT64Description:
Returns the count of documents from the previous stage whereexpressionevaluates to any non-NULL value. If noexpression is provided, returns thetotal count of documents from the previous stage.
Node.js
// Total number of books in the collectionconstcountOfAll=awaitdb.pipeline().collection("books").aggregate(countAll().as("count")).execute();// Number of books with nonnull `ratings` fieldconstcountField=awaitdb.pipeline().collection("books").aggregate(field("ratings").count().as("count")).execute();
Web
// Total number of books in the collectionconstcountOfAll=awaitexecute(db.pipeline().collection("books").aggregate(countAll().as("count")));// Number of books with nonnull `ratings` fieldconstcountField=awaitexecute(db.pipeline().collection("books").aggregate(field("ratings").count().as("count")));
Swift
// Total number of books in the collectionletcountAll=tryawaitdb.pipeline().collection("books").aggregate([CountAll().as("count")]).execute()// Number of books with nonnull `ratings` fieldletcountField=tryawaitdb.pipeline().collection("books").aggregate([Field("ratings").count().as("count")]).execute()
Kotlin
// Total number of books in the collectionvalcountAll=db.pipeline().collection("books").aggregate(AggregateFunction.countAll().alias("count")).execute()// Number of books with nonnull `ratings` fieldvalcountField=db.pipeline().collection("books").aggregate(AggregateFunction.count("ratings").alias("count")).execute()
Java
// Total number of books in the collectionTask<Pipeline.Snapshot>countAll=db.pipeline().collection("books").aggregate(AggregateFunction.countAll().alias("count")).execute();// Number of books with nonnull `ratings` fieldTask<Pipeline.Snapshot>countField=db.pipeline().collection("books").aggregate(AggregateFunction.count("ratings").alias("count")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportCount# Total number of books in the collectioncount_all=(client.pipeline().collection("books").aggregate(Count().as_("count")).execute())# Number of books with nonnull `ratings` fieldcount_field=(client.pipeline().collection("books").aggregate(Count("ratings").as_("count")).execute())
Java
// Total number of books in the collectionPipeline.SnapshotcountAll=firestore.pipeline().collection("books").aggregate(countAll().as("count")).execute().get();// Number of books with nonnull `ratings` fieldPipeline.SnapshotcountField=firestore.pipeline().collection("books").aggregate(count("ratings").as("count")).execute().get();
COUNT_IF
Syntax:
count_if(expression: BOOLEAN) -> INT64Description:
Returns the number of documents from the previous stage whereexpressionevaluates toTRUE.
Node.js
constresult=awaitdb.pipeline().collection("books").aggregate(field("rating").greaterThan(4).countIf().as("filteredCount")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("books").aggregate(field("rating").greaterThan(4).countIf().as("filteredCount")));
Swift
letresult=tryawaitdb.pipeline().collection("books").aggregate([AggregateFunction("count_if",[Field("rating").greaterThan(4)]).as("filteredCount")]).execute()
Kotlin
valresult=db.pipeline().collection("books").aggregate(AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("books").aggregate(AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("books").aggregate(Field.of("rating").greater_than(4).count_if().as_("filteredCount")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("books").aggregate(countIf(field("rating").greaterThan(4)).as("filteredCount")).execute().get();
COUNT_DISTINCT
Syntax:
count_distinct(expression: ANY) -> INT64Description:
Returns the number of unique non-NULL, non-ABSENT values ofexpression.
Node.js
constresult=awaitdb.pipeline().collection("books").aggregate(field("author").countDistinct().as("unique_authors")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("books").aggregate(field("author").countDistinct().as("unique_authors")));
Swift
letresult=tryawaitdb.pipeline().collection("books").aggregate([AggregateFunction("count_distinct",[Field("author")]).as("unique_authors")]).execute()
Kotlin
valresult=db.pipeline().collection("books").aggregate(AggregateFunction.countDistinct("author").alias("unique_authors")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("books").aggregate(AggregateFunction.countDistinct("author").alias("unique_authors")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("books").aggregate(Field.of("author").count_distinct().as_("unique_authors")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("books").aggregate(countDistinct("author").as("unique_authors")).execute().get();
SUM
Syntax:
sum(expression: ANY) -> NUMBERDescription:
Returns the sum for all numerical values, ignoring non-numeric values. ReturnsNaN if any values areNaN.
The output will have the same type as the widest input type except in these cases:
- An
INTEGERwill be converted to aDOUBLEif it cannot be represented as anINTEGER.
Node.js
constresult=awaitdb.pipeline().collection("cities").aggregate(field("population").sum().as("totalPopulation")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("cities").aggregate(field("population").sum().as("totalPopulation")));
Swift
letresult=tryawaitdb.pipeline().collection("cities").aggregate([Field("population").sum().as("totalPopulation")]).execute()
Kotlin
valresult=db.pipeline().collection("cities").aggregate(AggregateFunction.sum("population").alias("totalPopulation")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("cities").aggregate(AggregateFunction.sum("population").alias("totalPopulation")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("cities").aggregate(Field.of("population").sum().as_("totalPopulation")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("cities").aggregate(sum("population").as("totalPopulation")).execute().get();
AVERAGE
Syntax:
average(expression: ANY) -> FLOAT64Description:
Returns the average for all numerical values, ignoring non-numeric values.Evaluates toNaN if any values areNaN, orNULL if no numerical values areaggregated.
The output will have the same type as the input type except in these cases:
- An
INTEGERwill be converted to aDOUBLEif it cannot be represented as anINTEGER.
Node.js
constresult=awaitdb.pipeline().collection("cities").aggregate(field("population").average().as("averagePopulation")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("cities").aggregate(field("population").average().as("averagePopulation")));
Swift
letresult=tryawaitdb.pipeline().collection("cities").aggregate([Field("population").average().as("averagePopulation")]).execute()
Kotlin
valresult=db.pipeline().collection("cities").aggregate(AggregateFunction.average("population").alias("averagePopulation")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("cities").aggregate(AggregateFunction.average("population").alias("averagePopulation")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("cities").aggregate(Field.of("population").average().as_("averagePopulation")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("cities").aggregate(average("population").as("averagePopulation")).execute().get();
MINIMUM
Syntax:
minimum(expression: ANY) -> ANYDescription:
Returns the minimum non-NULL, non-absent value of theexpression when evaluated on each document.
If there are no non-NULL, non-absent values,NULL is returned. This includes when no documents are considered.
If there are multiple minimum equivalent values, any one of those values can be returned. Value type ordering followsdocumented ordering.
Node.js
constresult=awaitdb.pipeline().collection("books").aggregate(field("price").minimum().as("minimumPrice")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("books").aggregate(field("price").minimum().as("minimumPrice")));
Swift
letresult=tryawaitdb.pipeline().collection("books").aggregate([Field("price").minimum().as("minimumPrice")]).execute()
Kotlin
valresult=db.pipeline().collection("books").aggregate(AggregateFunction.minimum("price").alias("minimumPrice")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("books").aggregate(AggregateFunction.minimum("price").alias("minimumPrice")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("books").aggregate(Field.of("price").minimum().as_("minimumPrice")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("books").aggregate(minimum("price").as("minimumPrice")).execute().get();
MAXIMUM
Syntax:
maximum(expression: ANY) -> ANYDescription:
Returns the maximum non-NULL, non-absent value of theexpression when evaluated on each document.
If there are no non-NULL, non-absent values,NULL is returned. This includes when no documents are considered.
If there are multiple maximum equivalent values, any one of those values can be returned. Value type ordering followsdocumented ordering.
Node.js
constresult=awaitdb.pipeline().collection("books").aggregate(field("price").maximum().as("maximumPrice")).execute();
Web
constresult=awaitexecute(db.pipeline().collection("books").aggregate(field("price").maximum().as("maximumPrice")));
Swift
letresult=tryawaitdb.pipeline().collection("books").aggregate([Field("price").maximum().as("maximumPrice")]).execute()
Kotlin
valresult=db.pipeline().collection("books").aggregate(AggregateFunction.maximum("price").alias("maximumPrice")).execute()
Java
Task<Pipeline.Snapshot>result=db.pipeline().collection("books").aggregate(AggregateFunction.maximum("price").alias("maximumPrice")).execute();
Python
fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresult=(client.pipeline().collection("books").aggregate(Field.of("price").maximum().as_("maximumPrice")).execute())
Java
Pipeline.Snapshotresult=firestore.pipeline().collection("books").aggregate(maximum("price").as("maximumPrice")).execute().get();
FIRST
Syntax:
first(expression: ANY) -> ANYDescription:
Returns the value ofexpression for the first returned document.
LAST
Syntax:
last(expression: ANY) -> ANYDescription:
Returns the value ofexpression for the last returned document.
ARRAY_AGG
Syntax:
array_agg(expression: ANY) -> ARRAY<ANY>Description:
Returns an array containing all values ofexpression when evaluated on each document.
If the expression resolves to an absent value, it is converted toNULL.
The order of elements in the output array is not stable and shouldn't be relied upon.
ARRAY_AGG_DISTINCT
Syntax:
array_agg_distinct(expression: ANY) -> ARRAY<ANY>Description:
Returns an array containing all distinct values ofexpression when evaluated on each document.
If the expression resolves to an absent value, it is converted toNULL.
The order of elements in the output array is not stable and shouldn't be relied upon.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-18 UTC.