When to Maintain Write-Time Aggregates for Realtime Display vs Run Read-Time Aggregations

1. AtlasMart problem: rating average appears on every product card

A query-time average is elegant for occasional detail views. It is less attractive when the same value is rendered on hundreds of cards, refreshed often, expected to update through a realtime listener, or computed across a growing review set. A materialized aggregate stores a derived summary as a normal Firestore document. Reads become cheap and listenable, but every source mutation now has to maintain derived state correctly.

Learning outcomes

2. Same source truth, four read models

No row wins universally. The correct choice depends on how often the value changes, how often it is read, freshness requirements, contention, cost model, and operational appetite for repair.

3. Pattern A: synchronous transaction-maintained summary

import { FieldValue } from "firebase-admin/firestore";export async function createPublishedReviewWithSummary(db, productId, reviewId, review) {  const reviewRef = db.doc(`products/${productId}/reviews/${reviewId}`);  const summaryRef = db.doc(`products/${productId}/metrics/ratings`);  await db.runTransaction(async (tx) => {    const current = await tx.get(summaryRef);    const s = current.exists ? current.data() : { numericCount: 0, ratingSum: 0 };    const isNumeric = Number.isFinite(review.rating);    const numericCount = s.numericCount + (isNumeric ? 1 : 0);    const ratingSum = s.ratingSum + (isNumeric ? review.rating : 0);    tx.create(reviewRef, review);    tx.set(summaryRef, {      public: true,      publishedCount: FieldValue.increment(1),      numericCount,      ratingSum,      ratingAverage: numericCount ? ratingSum / numericCount : null,      updatedAt: FieldValue.serverTimestamp(),      source: "transaction"    }, { merge: true });  });}// The review and summary are atomic here, but the summary document can become a hotspot.// External side effects still do not belong inside the retryable transaction callback.

This pattern makes creation of a published review and update of its rating summary atomic. It is compelling when the source write path is centralized and write rate is comfortably below a hot-document contention threshold. The transaction callback may retry, so external side effects still stay outside it. If many independent writers all update products/p-1001/metrics/ratings, that summary document becomes a shared contention point.

4. Pattern B: asynchronous idempotent materializer

import { FieldValue } from "firebase-admin/firestore";export async function applyReviewEvent(db, event) {  const eventRef = db.doc(`aggregateEvents/${event.id}`);  const summaryRef = db.doc(`products/${event.productId}/metrics/ratings`);  await db.runTransaction(async (tx) => {    if ((await tx.get(eventRef)).exists) return; // deduplicate replay    const summary = await tx.get(summaryRef);    const s = summary.exists ? summary.data() : { numericCount: 0, ratingSum: 0 };    const deltaCount = Number.isFinite(event.rating) ? event.direction : 0;    const deltaSum = Number.isFinite(event.rating) ? event.direction * event.rating : 0;    const numericCount = s.numericCount + deltaCount;    const ratingSum = s.ratingSum + deltaSum;    tx.set(eventRef, {      appliedAt: FieldValue.serverTimestamp(),      productId: event.productId,      direction: event.direction    });    tx.set(summaryRef, {      public: true,      numericCount,      ratingSum,      ratingAverage: numericCount ? ratingSum / numericCount : null,      source: "event-materializer",      updatedAt: FieldValue.serverTimestamp()    }, { merge: true });  });}

Asynchronous processing breaks the atomic boundary: the review can commit before the summary changes. That creates an explicit consistency window. The durable aggregateEvents/{eventId} record makes duplicate delivery harmless at the database layer. This mirrors the at-least-once event reality established in Chapter 10. The UI may listen to the summary, but the summary itself can still lag the source event.

5. Pattern C: distributed count/sum shards

import { FieldValue } from "firebase-admin/firestore";import { randomInt } from "node:crypto";const SHARDS = 8;export async function addRatingToShard(db, productId, numericRating) {  const shard = String(randomInt(0, SHARDS)).padStart(2, "0");  await db.doc(`products/${productId}/ratingCounterShards/${shard}`).set({    numericCount: FieldValue.increment(1),    ratingSum: FieldValue.increment(numericRating)  }, { merge: true });}export async function readRatingShards(db, productId) {  const snap = await db.collection(`products/${productId}/ratingCounterShards`).get();  let numericCount = 0, ratingSum = 0;  for (const doc of snap.docs) {    numericCount += doc.get("numericCount") ?? 0;    ratingSum += doc.get("ratingSum") ?? 0;  }  return {    numericCount,    ratingSum,    ratingAverage: numericCount ? ratingSum / numericCount : null,    shardReads: snap.size  };}

For additive metrics, shards distribute write pressure. Average is derived as sum / count. The tradeoff moves to reads: exact shard aggregation requires reading each shard, and more shards mean more read work. A slower roll-up document can reduce client reads at the cost of bounded staleness. This is a good example of intentionally exchanging write distribution for read complexity.

6. Repair is part of the design

import { AggregateField, FieldValue } from "firebase-admin/firestore";export async function reconcileRatings(db, productId) {  const q = db.collection(`products/${productId}/reviews`).where("published", "==", true);  const truth = (await q.aggregate({    publishedCount: AggregateField.count(),    ratingSum: AggregateField.sum("rating"),    ratingAverage: AggregateField.average("rating")  }).get()).data();  await db.doc(`products/${productId}/metrics/ratings`).set({    public: true,    ...truth,    source: "reconciliation",    reconciledAt: FieldValue.serverTimestamp()  }, { merge: true });  return truth;}

Derived state should be treated as rebuildable. Reconciliation compares the materialized value against source truth and records when the repair happened. In the local fixture, the expected published review truth is count=5, numeric sum=12, and average=4. A repair job that produces a different answer is either exposing data drift or using a different query population—both deserve investigation.

7. Deliberately wrong approach: non-idempotent trigger increments forever

A function receives a review-created event and executes FieldValue.increment(1) without deduplicating the event. If the event is delivered twice, the counter is wrong. Retrying the trigger makes the damage worse, not better. Repair it by giving every logical change a durable event identity, applying it transactionally once, recording application evidence, and retaining a reconciliation path that can rebuild the summary.

8. Cost and correctness surface

9. Security boundary for derived documents

Clients that may read a product summary do not automatically need permission to write it. A safe pattern is public/readable metrics with writes denied to untrusted clients; a trusted backend or tightly validated transaction updates the summary. If client-side transactions maintain the aggregate, Rules must validate both the source document and aggregate invariants across the write set, which adds complexity and access-call pressure. Prefer the simplest trust path that meets the product requirement.

Production judgment and bridge to Lesson 4

Materialization is an operational feature, not a cache checkbox. It introduces lag targets, deduplication, contention, repair and monitoring. When the question expands from “current rating average” to “monthly revenue by seller, region, category, cohort and campaign over years,” even a well-designed materialized Firestore document is the wrong analytical substrate. Lesson 4 draws that boundary.

Knowledge check

1. What new failure mode appears when an aggregate is materialized?
2. Why can a single materialized summary become a hotspot?
3. What does a distributed counter trade?
4. Can a listener make an asynchronous summary exactly realtime?
5. What is the safest mindset for derived aggregate data?

Summary

AtlasMart can now choose between no-derived-state query-time arithmetic, a low-read materialized summary, or distributed additive shards, with lag, contention and repair made explicit.

Authoritative references

• Summarize data with aggregation queries
• Understand Cloud Firestore billing
• Write-time aggregations
• Distributed counters
• Securely query data
• Connect to the Firestore Emulator and emulator differences
• Firestore Standard Core operations overview
• Firestore Enterprise Native Core/Pipeline overview
• Enterprise Pipeline aggregate stage
• Enterprise pricing examples
• MongoDB compatibility behavior differences
• Managed Firestore export/import
• Firebase Extensions migration guidance, including Stream Firestore to BigQuery
• Firebase JavaScript SDK release notes
• Firebase Admin Node.js SDK release notes