Agregações no momento da escrita
As consultas no Firestore permitem-lhe encontrar documentos em grandes coleções. Para obter estatísticas sobre as propriedades da coleção como um todo, pode agregar dados numa coleção.
Pode agregar dados no momento da leitura ou no momento da escrita:
As agregações em tempo de leitura calculam um resultado no momento do pedido. O Firestore suporta as consultas de agregação
count(),sum()eaverage()no momento da leitura. As consultas de agregação no momento da leitura são mais fáceis de adicionar à sua app do que as agregações no momento da escrita. Para mais informações sobre consultas de agregação, consulte o artigo Resuma os dados com consultas de agregação.As agregações no momento da gravação calculam um resultado sempre que a app realiza uma operação de gravação relevante. As agregações no momento da gravação exigem mais trabalho de implementação, mas pode usá-las em vez das agregações no momento da leitura por um dos seguintes motivos:
- Quiser ouvir o resultado da agregação para atualizações em tempo real.
As consultas de agregação
count(),sum()eaverage()não suportam atualizações em tempo real. - Quer armazenar o resultado da agregação numa cache do lado do cliente.
As consultas de agregação
count(),sum()eaverage()não suportam o armazenamento em cache. - Está a agregar dados de dezenas de milhares de documentos para cada um dos seus utilizadores e a considerar os custos. Com um número inferior de documentos, as agregações de tempo de leitura custam menos. Para um grande número de documentos numa agregação, as agregações no momento da gravação podem custar menos.
- Quiser ouvir o resultado da agregação para atualizações em tempo real.
As consultas de agregação
Pode implementar uma agregação no momento da gravação através de uma transação do lado do cliente ou com funções do Cloud Run. As secções seguintes descrevem como implementar agregações no momento da gravação.
Solução: agregação no momento da escrita com uma transação do lado do cliente
Considere uma app de recomendações locais que ajuda os utilizadores a encontrar excelentes restaurantes. A seguinte consulta obtém todas as classificações de um determinado restaurante:
Web
db.collection("restaurants") .doc("arinell-pizza") .collection("ratings") .get();
Swift
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
do { let snapshot = try await db.collection("restaurants") .document("arinell-pizza") .collection("ratings") .getDocuments() print(snapshot) } catch { print(error) }
Objective-C
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
FIRQuery *query = [[[self.db collectionWithPath:@"restaurants"] documentWithPath:@"arinell-pizza"] collectionWithPath:@"ratings"]; [query getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot, NSError * _Nullable error) { // ... }];
Kotlin
Android
db.collection("restaurants") .document("arinell-pizza") .collection("ratings") .get()
Java
Android
db.collection("restaurants") .document("arinell-pizza") .collection("ratings") .get();
Em vez de obter todas as classificações e, em seguida, calcular as informações agregadas, podemos armazenar estas informações no próprio documento do restaurante:
Web
var arinellDoc = { name: 'Arinell Pizza', avgRating: 4.65, numRatings: 683 };
Swift
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
struct Restaurant { let name: String let avgRating: Float let numRatings: Int } let arinell = Restaurant(name: "Arinell Pizza", avgRating: 4.65, numRatings: 683)
Objective-C
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
@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
Kotlin
Android
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)
Java
Android
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);
Para manter estas agregações consistentes, têm de ser atualizadas sempre que é adicionada uma nova classificação à subcoleção. Uma forma de alcançar a consistência é fazer a adição e a atualização numa única transação:
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
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
func addRatingTransaction(restaurantRef: DocumentReference, rating: Float) async { let ratingRef: DocumentReference = restaurantRef.collection("ratings").document() do { let _ = try await 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 }) } catch { // ... } }
Objective-C
Nota: este produto não está disponível em alvos do watchOS e de App Clips.
- (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) { // ... }]; }
Kotlin
Android
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>()!! // 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 } }
Java
Android
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(@NonNull 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; } }); }
A utilização de uma transação mantém os dados agregados consistentes com a recolha subjacente. Para ler mais acerca das transações no Firestore, consulte o artigo Transações e gravações em lote.
Limitações
A solução apresentada acima demonstra a agregação de dados através da biblioteca de cliente do Firestore, mas deve ter em atenção as seguintes limitações:
- Segurança: as transações do lado do cliente requerem que conceda autorização aos clientes para atualizarem os dados agregados na sua base de dados. Embora possa reduzir os riscos desta abordagem escrevendo regras de segurança avançadas, esta pode não ser adequada em todas as situações.
- Suporte offline: as transações do lado do cliente falham quando o dispositivo do utilizador está offline, o que significa que tem de processar este caso na sua app e tentar novamente no momento adequado.
- Desempenho: se a sua transação contiver várias operações de leitura, escrita e atualização, pode exigir vários pedidos ao back-end do Firestore. Num dispositivo móvel, este processo pode demorar muito tempo.
- Taxas de gravação: esta solução pode não funcionar para agregações atualizadas com frequência, uma vez que os documentos do Cloud Firestore só podem ser atualizados, no máximo, uma vez por segundo. Além disso, se uma transação ler um documento que foi modificado fora da transação, tenta um número finito de vezes e, em seguida, falha. Consulte os contadores distribuídos para ver uma solução alternativa relevante para agregações que precisam de atualizações mais frequentes.
Solução: agregação no momento da escrita com o Cloud Functions
Se as transações do lado do cliente não forem adequadas para a sua aplicação, pode usar uma função do Google Cloud para atualizar as informações agregadas sempre que uma nova classificação for adicionada a um restaurante:
Node.js
exports.aggregateRatings = functions.firestore .document('restaurants/{restId}/ratings/{ratingId}') .onWrite(async (change, context) => { // Get value of the newly added rating const ratingVal = change.after.data().rating; // Get a reference to the restaurant const restRef = db.collection('restaurants').doc(context.params.restId); // Update aggregations in a transaction await db.runTransaction(async (transaction) => { const restDoc = await transaction.get(restRef); // Compute new number of ratings const newNumRatings = restDoc.data().numRatings + 1; // Compute new average rating const oldRatingTotal = restDoc.data().avgRating * restDoc.data().numRatings; const newAvgRating = (oldRatingTotal + ratingVal) / newNumRatings; // Update restaurant info transaction.update(restRef, { avgRating: newAvgRating, numRatings: newNumRatings }); }); });
Esta solução transfere o trabalho do cliente para uma função alojada, o que significa que a sua app para dispositivos móveis pode adicionar classificações sem esperar que uma transação seja concluída. O código executado numa Cloud Function não está sujeito a regras de segurança, o que significa que já não tem de conceder aos clientes acesso de escrita aos dados agregados.
Limitações
A utilização de uma função do Google Cloud para agregações evita alguns dos problemas com as transações do lado do cliente, mas tem um conjunto diferente de limitações:
- Custo: cada classificação adicionada vai provocar uma invocação da Cloud Function, o que pode aumentar os seus custos. Para mais informações, consulte a página de preços do Cloud Functions.
- Latência: ao transferir o trabalho de agregação para uma Cloud Function, a sua app não vê dados atualizados até que a Cloud Function termine a execução e o cliente seja notificado dos novos dados. Consoante a velocidade da sua função na nuvem, isto pode demorar mais tempo do que executar a transação localmente.
- Taxas de gravação: esta solução pode não funcionar para agregações atualizadas com frequência, uma vez que os documentos do Cloud Firestore só podem ser atualizados, no máximo, uma vez por segundo. Além disso, se uma transação ler um documento que foi modificado fora da transação, tenta um número finito de vezes e, em seguida, falha. Consulte os contadores distribuídos para ver uma solução alternativa relevante para agregações que precisam de atualizações mais frequentes.