Advanced queries in Cloud Firestore allow you to quickly find documents in large collections. If you want to gain insight into properties of the collection as a whole, you will need aggregation over a collection.
Cloud Firestore does not support native aggregation queries. However, you can use client-side transactions or Cloud Functions to easily maintain aggregate information about your data.
Before continuing, make sure you have read about queries and the Cloud Firestore data model.
Solution: Client-side transactions
Consider a local recommendations app that helps users find great restaurants. The following query retrieves all the ratings for a given restaurant:
Web
db.collection("restaurants")
.doc("arinell-pizza")
.collection("ratings")
.get()
Swift
db.collection("restaurants")
.document("arinell-pizza")
.collection("ratings")
.getDocuments() { (querySnapshot, err) in
// ...
}
Objective-C
FIRQuery *query = [[[self.db collectionWithPath:@"restaurants"]
documentWithPath:@"arinell-pizza"] collectionWithPath:@"ratings"];
[query getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot,
NSError * _Nullable error) {
// ...
}];
Java
db.collection("restaurants")
.document("arinell-pizza")
.collection("ratings")
.get();Kotlin
db.collection("restaurants")
.document("arinell-pizza")
.collection("ratings")
.get()Rather than fetching all ratings and then computing aggregate information, we can store this information on the restaurant document itself:
Web
var arinellDoc = {
name: 'Arinell Pizza',
avgRating: 4.65,
numRatings: 683
}
Swift
struct Restaurant {
let name: String
let avgRating: Float
let numRatings: Int
init(name: String, avgRating: Float, numRatings: Int) {
self.name = name
self.avgRating = avgRating
self.numRatings = numRatings
}
}
let arinell = Restaurant(name: "Arinell Pizza", avgRating: 4.65, numRatings: 683)
Objective-C
@interface FIRRestaurant : NSObject
@property (nonatomic, readonly) NSString *name;
@property (nonatomic, readonly) float averageRating;
@property (nonatomic, readonly) NSInteger ratingCount;
- (instancetype)initWithName:(NSString *)name
averageRating:(float)averageRating
ratingCount:(NSInteger)ratingCount;
@end
@implementation FIRRestaurant
- (instancetype)initWithName:(NSString *)name
averageRating:(float)averageRating
ratingCount:(NSInteger)ratingCount {
self = [super init];
if (self != nil) {
_name = name;
_averageRating = averageRating;
_ratingCount = ratingCount;
}
return self;
}
@end
Java
public class Restaurant {
String name;
double avgRating;
int numRatings;
public Restaurant(String name, double avgRating, int numRatings) {
this.name = name;
this.avgRating = avgRating;
this.numRatings = numRatings;
}
}
Restaurant arinell = new Restaurant("Arinell Pizza", 4.65, 683);Kotlin
data class Restaurant(
// default values required for use with "toObject"
internal var name: String = "",
internal var avgRating: Double = 0.0,
internal var numRatings: Int = 0
)
val arinell = Restaurant("Arinell Pizza", 4.65, 683)In order to keep these aggregations consistent, they must be updated each time a new rating is added to the subcollection. One way to achieve consistency is to perform the add and the update in a single transaction:
Web
function addRating(restaurantRef, rating) {
// Create a reference for a new rating, for use inside the transaction
var ratingRef = restaurantRef.collection('ratings').doc();
// In a transaction, add the new rating and update the aggregate totals
return db.runTransaction(transaction => {
return transaction.get(restaurantRef).then(res => {
if (!res.exists) {
throw "Document does not exist!";
}
// Compute new number of ratings
var newNumRatings = res.data().numRatings + 1;
// Compute new average rating
var oldRatingTotal = res.data().avgRating * res.data().numRatings;
var newAvgRating = (oldRatingTotal + rating) / newNumRatings;
// Commit to Firestore
transaction.update(restaurantRef, {
numRatings: newNumRatings,
avgRating: newAvgRating
});
transaction.set(ratingRef, { rating: rating });
})
});
}
Swift
func addRatingTransaction(restaurantRef: DocumentReference, rating: Float) {
let ratingRef: DocumentReference = restaurantRef.collection("ratings").document()
db.runTransaction({ (transaction, errorPointer) -> Any? in
do {
let restaurantDocument = try transaction.getDocument(restaurantRef).data()
guard var restaurantData = restaurantDocument else { return nil }
// Compute new number of ratings
let numRatings = restaurantData["numRatings"] as! Int
let newNumRatings = numRatings + 1
// Compute new average rating
let avgRating = restaurantData["avgRating"] as! Float
let oldRatingTotal = avgRating * Float(numRatings)
let newAvgRating = (oldRatingTotal + rating) / Float(newNumRatings)
// Set new restaurant info
restaurantData["numRatings"] = newNumRatings
restaurantData["avgRating"] = newAvgRating
// Commit to Firestore
transaction.setData(restaurantData, forDocument: restaurantRef)
transaction.setData(["rating": rating], forDocument: ratingRef)
} catch {
// Error getting restaurant data
// ...
}
return nil
}) { (object, err) in
// ...
}
}
Objective-C
- (void)addRatingTransactionWithRestaurantReference:(FIRDocumentReference *)restaurant
rating:(float)rating {
FIRDocumentReference *ratingReference =
[[restaurant collectionWithPath:@"ratings"] documentWithAutoID];
[self.db runTransactionWithBlock:^id (FIRTransaction *transaction,
NSError **errorPointer) {
FIRDocumentSnapshot *restaurantSnapshot =
[transaction getDocument:restaurant error:errorPointer];
if (restaurantSnapshot == nil) {
return nil;
}
NSMutableDictionary *restaurantData = [restaurantSnapshot.data mutableCopy];
if (restaurantData == nil) {
return nil;
}
// Compute new number of ratings
NSInteger ratingCount = [restaurantData[@"numRatings"] integerValue];
NSInteger newRatingCount = ratingCount + 1;
// Compute new average rating
float averageRating = [restaurantData[@"avgRating"] floatValue];
float newAverageRating = (averageRating * ratingCount + rating) / newRatingCount;
// Set new restaurant info
restaurantData[@"numRatings"] = @(newRatingCount);
restaurantData[@"avgRating"] = @(newAverageRating);
// Commit to Firestore
[transaction setData:restaurantData forDocument:restaurant];
[transaction setData:@{@"rating": @(rating)} forDocument:ratingReference];
return nil;
} completion:^(id _Nullable result, NSError * _Nullable error) {
// ...
}];
}
Java
private Task<Void> addRating(final DocumentReference restaurantRef, final float rating) {
// Create reference for new rating, for use inside the transaction
final DocumentReference ratingRef = restaurantRef.collection("ratings").document();
// In a transaction, add the new rating and update the aggregate totals
return db.runTransaction(new Transaction.Function<Void>() {
@Override
public Void apply(Transaction transaction) throws FirebaseFirestoreException {
Restaurant restaurant = transaction.get(restaurantRef).toObject(Restaurant.class);
// Compute new number of ratings
int newNumRatings = restaurant.numRatings + 1;
// Compute new average rating
double oldRatingTotal = restaurant.avgRating * restaurant.numRatings;
double newAvgRating = (oldRatingTotal + rating) / newNumRatings;
// Set new restaurant info
restaurant.numRatings = newNumRatings;
restaurant.avgRating = newAvgRating;
// Update restaurant
transaction.set(restaurantRef, restaurant);
// Update rating
Map<String, Object> data = new HashMap<>();
data.put("rating", rating);
transaction.set(ratingRef, data, SetOptions.merge());
return null;
}
});
}Kotlin
private fun addRating(restaurantRef: DocumentReference, rating: Float): Task<Void> {
// Create reference for new rating, for use inside the transaction
val ratingRef = restaurantRef.collection("ratings").document()
// In a transaction, add the new rating and update the aggregate totals
return db.runTransaction { transaction ->
val restaurant = transaction.get(restaurantRef).toObject(Restaurant::class.java)!!
// Compute new number of ratings
val newNumRatings = restaurant.numRatings + 1
// Compute new average rating
val oldRatingTotal = restaurant.avgRating * restaurant.numRatings
val newAvgRating = (oldRatingTotal + rating) / newNumRatings
// Set new restaurant info
restaurant.numRatings = newNumRatings
restaurant.avgRating = newAvgRating
// Update restaurant
transaction.set(restaurantRef, restaurant)
// Update rating
val data = hashMapOf<String, Any>(
"rating" to rating
)
transaction.set(ratingRef, data, SetOptions.merge())
null
}
}Using a transaction keeps your aggregate data consistent with the underlying collection. To read more about transactions in Cloud Firestore, see Transactions and Batched Writes.
Limitations
The solution shown above demonstrates aggregating data using the Cloud Firestore client library, but you should be aware of the following limitations:
- Security - Client-side transactions require giving clients permission to update the aggregate data in your database. While you can reduce the risks of this approach by writing advanced security rules, this may not be appropriate in all situations.
- Offline support - Client-side transactions will fail when the user's device is offline, which means you need to handle this case in your app and retry at the appropriate time.
- Performance - If your transaction contains multiple read, write, and update operations, it could require multiple requests to the Cloud Firestore backend. On a mobile device, this could take significant time.
Solution: Cloud Functions
If client-side transactions are not suitable for your application, you can use a Cloud Function to update the aggregate information each time a new rating is added to a restaurant:
Node.js
exports.aggregateRatings = functions.firestore
.document('restaurants/{restId}/ratings/{ratingId}')
.onWrite((change, context) => {
// Get value of the newly added rating
var ratingVal = change.after.data().rating;
// Get a reference to the restaurant
var restRef = db.collection('restaurants').doc(context.params.restId);
// Update aggregations in a transaction
return db.runTransaction(transaction => {
return transaction.get(restRef).then(restDoc => {
// Compute new number of ratings
var newNumRatings = restDoc.data().numRatings + 1;
// Compute new average rating
var oldRatingTotal = restDoc.data().avgRating * restDoc.data().numRatings;
var newAvgRating = (oldRatingTotal + ratingVal) / newNumRatings;
// Update restaurant info
return transaction.update(restRef, {
avgRating: newAvgRating,
numRatings: newNumRatings
});
});
});
});
This solution offloads the work from the client to a hosted function, which means your mobile app can add ratings without waiting for a transaction to complete. Code executed in a Cloud Function is not bound by security rules, which means you no longer need to give clients write access to the aggregate data.
Limitations
Using a Cloud Function for aggregations avoids some of the issues with client-side transactions, but comes with a different set of limitations:
- Cost - Each rating added will cause a Cloud Function invocation, which may increase your costs. For more information, see the Cloud Functions pricing page.
- Latency - By offloading the aggregation work to a Cloud Function, your app will not see updated data until the Cloud Function has finished executing and the client has been notified of the new data. Depending on the speed of your Cloud Function, this could take longer than executing the transaction locally.