In a Firestore task app, every task change also updates an openTaskCount field on the project document; why does this degrade as the team grows, and what do you change?
answer
- one document, many writers
- quorum write plus index updates
- an increment is still a write
- spread the count over shards
- count() for the badge
basics
~20 sEvery task change funnels a write into one project document, and a single Firestore document sustains only a limited write rate, so contention brings latency, retries and errors. Use FieldValue.increment, shard the counter across documents, or compute it with count().
solid answer
~50 sThe project document becomes a **hot document**. Firestore applies each write synchronously across a quorum of replicas and updates every index that includes the document. The rate one document can sustain depends on the workload, and the docs give no fixed number. Past it you see contention, higher latency and errors. If the client updates the counter in a transaction, each conflicting writer also reruns its function, up to five attempts by default, and then fails. I would first replace the read-then-write with `FieldValue.increment(1)` inside the same batch as the task write, which removes the reads and retries. That still sends one write per change to the same document, though. At real scale I would shard the counter across N documents and sum them on read, or stop storing it and show the badge from a `count()` aggregation.
code
kotlin · 17 linesimport com.google.android.gms.tasks.Task
import com.google.firebase.firestore.FieldValue
import com.google.firebase.firestore.FirebaseFirestore
import com.google.firebase.firestore.SetOptions
import kotlin.random.Random
const val SHARDS = 10
fun createTask(db: FirebaseFirestore, projectId: String, task: Map<String, Any>): Task<Void> {
val project = db.collection("projects").document(projectId)
val newTask = project.collection("tasks").document()
val shard = project.collection("counterShards").document(Random.nextInt(SHARDS).toString())
return db.runBatch { batch ->
batch.set(newTask, task)
batch.set(shard, mapOf("open" to FieldValue.increment(1)), SetOptions.merge())
}
}go deeper
Recall that every write to a shared field lands on one document, and that FieldValue.increment updates a number without reading it first.
Explain why a read-then-write counter in a transaction retries under concurrency, and what an increment inside a batch removes.
Diagnose the hot document from latency and contention errors, then choose between sharding, count() and server-side coalescing based on how live the number must be.
Decide which aggregates the product stores versus computes, size shard counts from load tests, and set conventions that keep hot paths off single documents.
## Why one document becomes the bottleneck In the team task app, each task create, complete or reopen also touches `projects/{projectId}.openTaskCount`. Ten people working on one project means every write in that project also writes **the same document**. The Firestore best-practices guide explains why that hurts. A document write updates the document **and every associated index**, and Firestore applies it **synchronously across a quorum of replicas**. The maximum rate for updating a single document *depends highly on the workload*: the write rate, contention among requests and the number of indexes affected. The guide gives no fixed number and recommends load testing. Past that rate the database starts to encounter **contention, higher latency or other errors**. ## How the symptom shows up on Android - If the client updates the counter by **reading it and writing count + 1** in `runTransaction`, every concurrent writer conflicts. The SDK reruns each function, up to **5 attempts** by default, and then fails the transaction. A busy project turns into a retry storm. - If the client writes blindly, there is no transaction rerun, but latency still grows and contention errors appear. - When the task write and the counter update share a batch, the task write now shares the counter's fate. ## Option 1: FieldValue.increment `FieldValue.increment(1)` asks the **server** to add to the current value, so the app needs no read and no transaction. Put it in the same `WriteBatch` as the task write and both stay atomic. The batch also works offline. This removes the read, the conflict check and the retry loop. It does **not** change the number of writes reaching the project document. Every task change is still one write to it. That is enough for a small team, but not for a project with a high, sustained write rate. ## Option 2: a distributed (sharded) counter Split the counter across N **shard documents**, for example `projects/{id}/counterShards/0` to `9`: 1. On every task change, pick a shard at random and apply `FieldValue.increment` to it, in the same batch as the task write. 2. To show the total, read all N shards and add their values. | | Single counter | N shards | |---|---|---| | Documents written per change | 1, always the same | 1, spread across N | | Reads to show the total | 1 | N | | Write-rate ceiling | one document's | roughly N documents' | The trade is explicit: more write throughput for N reads at display time. The number of shards is a capacity decision, sized from load testing. Keeping the shards in a subcollection of the project leaves the count next to the data it describes. Adding shards later is easy, but every extra shard costs one more read each time the total is shown. ## Option 3: do not store the count A `count()` aggregation computes the number on the server from index entries: - it returns only the result and is billed at **one read per batch of up to 1,000 index entries**; - it is answered **only by the backend**, so it cannot back a snapshot listener and does not work offline; - it scales with the number of index entries scanned, and fails with `DEADLINE_EXCEEDED` if it cannot finish within **60 seconds**. For very large datasets the docs point back to counters. For a badge refreshed when the screen opens, `count()` is often the simplest answer. For a number that must update live on every phone, a stored counter, sharded if needed, fits better. ## Option 4: let the server batch it Moving the counter into trusted server code that reacts to task writes takes the work off the clients. A trigger still writes a document, though, so the same per-document ceiling applies unless the server coalesces updates. The trigger mechanics belong with Cloud Functions. ## Related hotspots - **Sequential indexed fields.** An indexed field that increases with each new document, such as an `updatedAt` timestamp, caps writes to its collection at **500 per second**. Exempt it from indexing if no query uses it. - **Sequential IDs.** Monotonically increasing document IDs concentrate writes on lexicographically close documents. Automatic IDs are scattered. - **Sudden traffic.** For a new collection, the guide's **500/50/5** rule says to start at no more than 500 operations per second and increase by 50% every 5 minutes.
- What does FieldValue.increment change compared with a transaction that reads the count and writes count + 1?The server applies the increment, so the client sends one write with no read, no conflict check and no retry loop. It can sit in a batch with the task write and still work offline. It does not change how many writes reach the project document: every task change still lands there, so at high rates you still hit contention. Sharding the counter or not storing it addresses that.
- Why might count() be the better answer for the project badge?`count()` computes the number on the server from index entries and returns only the result, billed at one read per batch of up to 1,000 entries, so there is no counter document to fight over. The costs: it cannot feed a snapshot listener, it does not work offline, it rescans the index each time, and a very large count can fail with `DEADLINE_EXCEEDED` after 60 seconds.
- Besides a hot document, which index-driven write limit can a busy tasks collection hit?If an indexed field increases sequentially from document to document, such as an `updatedAt` timestamp, the indexing guide caps writes to that collection at 500 per second, because new index entries pile into one key range. If no query filters or sorts on that field, add a single-field index exemption to remove the cap.
One tip jar on a busy counter makes every customer queue to reach it. Put out ten jars and anyone can drop coins in at once, but whoever counts the takings has to empty all ten.
- Switching to FieldValue.increment removes the write-rate ceiling on the project document.
- Firestore queues writes to a hot document, so the only symptom is slower writes.
- A transaction on a contended document keeps retrying until it eventually wins.
- Sequential IDs like task0001 spread writes evenly across Firestore's storage.
- A sharded counter's total costs the same single read as an unsharded one.