Firestore Batched Writes: 500-Op Limit, 1 MB Ceiling, and When to Split

When you need to persist a set of document changes in Firestore and want the operation to be atomic, a batched write is the natural first approach. But the SDK silently enforces constraints that can cause silent failures or unexpected cost spikes if you're unaware of them. Use a batched write for up to 500 operations under 1 MB, and split or offload larger work.

The 500-Operation Ceiling

Firestore batched writes accept a maximum of 500 individual document operations. Each operation inside a batch must target a single document — you cannot add a collection group write or write to multiple documents within a single batch item. If you attempt to exceed this count, the SDK throws a client-side error before the request is sent, preventing partial commits.

The 1 MB Size Cap and Atomic Guarantee

Beyond operation count, the combined size of all document data and metadata in a single batch must stay under 1 megabyte. This includes the document path identifiers, field values, and any nested objects. The atomic guarantee means that if any single operation within the batch fails — whether due to security rules, document missing, or concurrent modification — the entire batch is rejected and no changes are persisted.

A Concrete Example: Writing 300 Profile Updates

Suppose you want to increment a score field for 300 user documents in one atomic step. Below is a conceptual pattern using the Firebase JavaScript SDK v9+:

import { getFirestore, writeBatch, doc } from "firebase/firestore"; const db = getFirestore(); const batch = writeBatch(db); for (const uid of userIds.slice(0, 300)) { const userRef = doc(db, "users", uid); batch.update(userRef, { lastUpdated: serverTimestamp() }); } batch.commit().then(() => { /* All 300 updates succeeded */ }).catch((error) => { /* The batch was rejected — check the error to understand why */ });

Important notes for this pattern:

1. Permission requirements: The authenticated user must have write permission on each targeted document path. Security rules that deny a single write will abort the whole batch.
2. Expected checks: Before calling commit(), verify that userIds.length <= 500 and that the serialized payload of all updates stays comfortably under the 1 MB ceiling (a rough heuristic: keep each update under ~2 KB).
3. Relevant risks: If any of the 300 documents is missing or the user lacks permission, the batch fails — zero changes are written. There is no partial success.

When to Split Batches or Reach for Cloud Functions

If your feature requires writing more than 500 documents, or the combined data exceeds 1 MB, you have two practical paths:

1. Split the work across multiple batched writes, each under the 500-op and 1 MB limits. You can orchestrate them sequentially or in parallel, handling errors per-batch.
2. Trigger a Cloud Function that uses the Admin SDK, which imposes slightly different quotas but gives you server-side control over batching, retries, and cost monitoring.

Large batches also increase latency. A batch of 500 writes that each read 1 KB will likely commit faster than a batch of 500 writes that each write 2 KB, simply because the network payload is smaller. Monitor request duration and Firestore quota metrics if you're batch-heavy.

Verifying Your Batch Limits Locally

1. Create a batch with 500 dummy write operations and call commit(). Observe that the call succeeds (or fails with a client-side error if the SDK version differs).
2. Attempt to add a 501st operation and commit again. The SDK should throw an error before the request leaves the client, confirming the 500-op hard limit.
3. Serialize the batch's write payload (the SDK exposes the internal structure in debug mode, or you can measure the JSON string length of all update/set/delete operations). Ensure the byte size stays under 1 048 576 bytes.

These steps help you catch size or count violations early, before they manifest as failed deploys or unexpected billing.

Closing: Choose the Right Tool for the Job

Firestore batched writes are a fast, client-side way to commit up to 500 atomic document operations under 1 MB. They're ideal for bulk profile updates, status changes, or small batch migrations. When your workload exceeds those boundaries, split the batches or offload the coordination to a Cloud Function. Always validate operation count and payload size before committing, and remember that a single failing operation rolls the entire batch back — so pre-validation via security rules or a quick pre-check loop is worth the few extra lines of code.