Sequential Document IDs / Timestamps, Monotonic Fields, High Write Rates, and Index Hotspots

1. Why a timestamp can hotspot even when document IDs are random

AtlasMart wisely stopped using event-000001, event-000002, … as document IDs and switched to Firestore auto IDs. Yet write latency rises as event volume grows. The overlooked field is ingestedAt: every new event receives a later timestamp, and Standard Native automatically indexes that field. The document keys are scattered, but the timestamp index entries arrive at one moving edge of an ordered index.

This is the key distinction: document-key hotspot and index-key hotspot are independent. Random IDs fix the first. A sequential indexed field can still create the second.

Learning outcomes

2. Two moving edges: document IDs and indexed values

Standard Native documentation states that when a collection contains a monotonically increasing or decreasing indexed field, the maximum write rate to that collection is 500 writes per second. This is not “all timestamp fields” and it is not the 500/50/5 ramp guideline. If the timestamp is not indexed, that specific index constraint does not apply; if the field is required for a query, simply disabling the index breaks the access pattern.

3. Start with the Chapter 5 query contracts

AtlasMart already treats queries as named contracts. Before changing indexing, add an inventory entry for every event query that consumes occurredAt or ingestedAt. A field can be safely exempted only when no required Standard query depends on it.

{  "indexes": [    {      "collectionGroup": "events",      "queryScope": "COLLECTION",      "fields": [        { "fieldPath": "tenantId", "order": "ASCENDING" },        { "fieldPath": "kind", "order": "ASCENDING" },        { "fieldPath": "occurredAt", "order": "DESCENDING" }      ]    }  ],  "fieldOverrides": [    {      "collectionGroup": "events",      "fieldPath": "ingestedAt",      "indexes": []    },    {      "collectionGroup": "events",      "fieldPath": "rawPayload",      "indexes": []    },    {      "collectionGroup": "events",      "fieldPath": "debugAttributes",      "indexes": []    }  ]}

4. When a required timestamp query must scale beyond one ordered index edge

The sharded timestamp pattern deliberately adds a small random shard value and indexes (timestampShard, occurredAt) instead of relying on one globally ordered timestamp edge. Writes are spread across shard-prefixed index ranges. Reads query each shard and merge the top results in application code. This trades write scalability for read amplification and application complexity; choose a shard count from measured workload, not folklore.

import { randomInt } from "node:crypto";import { Timestamp } from "firebase-admin/firestore";export async function writeEvent(db, event) {  const shard = randomInt(0, 16);  const occurredAt = Timestamp.fromDate(event.occurredAt);  const ref = db.collection("events").doc(); // Firestore-style scatter ID  await ref.set({    tenantId: event.tenantId,    kind: event.kind,    occurredAt,    timestampShard: shard,    ingestedAt: Timestamp.now(),    payload: event.payload  });  return ref.id;}// If a required query must order by a sequential timestamp at a write rate// beyond Standard's sequential-index constraint, query by shard + timestamp// and merge a bounded number of shard result sets in application code.

The query side must issue one bounded query per shard, preserve the same filters, then merge-sort by occurredAt. Pagination becomes a multi-cursor problem because each shard has its own continuation state. That complexity is the cost of distributing the ordered index.

5. Deliberately wrong approach: encode time in the document ID

20260917T010000Z-000001 looks operationally convenient because a console listing appears chronologically ordered. At high write rates it puts new document keys next to each other. Worse, if ingestedAt is also indexed, the same write can create both a document-key moving hotspot and an index-key moving hotspot.

The repair is to keep identity independent of sort order. Use scattered document IDs. Store time as data. Exempt unused sequential time fields in Standard, or shard the time index only when a required access pattern justifies the added complexity.

6. Edition-aware decision table

7. Observable lab: compare key-generation shapes, not production capacity

{  "name": "atlasmart-firestore-ch15",  "private": true,  "type": "module",  "engines": { "node": ">=22" },  "dependencies": {    "firebase-admin": "14.4.0"  },  "devDependencies": {    "firebase-tools": "15.30.0"  },  "scripts": {    "emulators": "firebase emulators:start --only firestore --project demo-atlasmart-firestore",    "bench": "node bench-writes.mjs",    "reset": "node reset-ch15.mjs"  }}

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getFirestore, FieldValue } from "firebase-admin/firestore";import { randomUUID } from "node:crypto";initializeApp({ projectId: "demo-atlasmart-firestore" });const db = getFirestore();const percentile = (sorted, p) => {  if (!sorted.length) return null;  const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);  return sorted[index];};async function runStage({ mode, writes, concurrency }) {  const latencies = [];  let next = 0;  let errors = 0;  async function worker(workerId) {    while (true) {      const i = next++;      if (i >= writes) return;      const started = performance.now();      try {        if (mode === "hot-document") {          await db.doc("benchmarks/ch15-hot").set({            n: FieldValue.increment(1),            updatedAt: FieldValue.serverTimestamp()          }, { merge: true });        } else {          const id = mode === "sequential"            ? `evt-${String(i).padStart(10, "0")}`            : `evt-${randomUUID()}`;          await db.doc(`benchmarks/ch15-${mode}/events/${id}`).set({            mode,            ordinal: i,            observedAt: new Date().toISOString(),            workerId          });        }      } catch (error) {        errors++;        console.error(JSON.stringify({ mode, i, code: error.code, message: error.message }));      } finally {        latencies.push(performance.now() - started);      }    }  }  const t0 = performance.now();  await Promise.all(Array.from({ length: concurrency }, (_, i) => worker(i)));  const elapsedMs = performance.now() - t0;  latencies.sort((a, b) => a - b);  return {    mode, writes, concurrency, elapsedMs,    observedOpsPerSecond: writes / (elapsedMs / 1000),    errors,    latencyMs: {      p50: percentile(latencies, 50),      p95: percentile(latencies, 95),      p99: percentile(latencies, 99),      max: latencies.at(-1)    }  };}for (const stage of [  { mode: "random", writes: 600, concurrency: 12 },  { mode: "sequential", writes: 600, concurrency: 12 },  { mode: "hot-document", writes: 250, concurrency: 12 }]) {  console.log(JSON.stringify(await runStage(stage)));}

Run the random and sequential stages several times after resetting emulator state. Preserve every JSON record. The lesson goal is to make the distinction between identifier strategies explicit and to verify that your harness records tail latency and errors. If one local mode looks faster, do not generalize it into a production claim; the emulator does not model managed key-range splitting.

8. Verification and rollback

• No product query relies on a field before you exempt its index.
• Sequential IDs are removed from high-rate event writes.
• If timestamp sharding is introduced, the shard count is configuration with a migration plan, not a magic constant.
• Pagination tests cover all shard cursors and duplicate/tie handling.
• The old query/index path remains available until new query-contract tests pass.

Production judgment and bridge to Lesson 3

Random IDs solve document-key distribution; index design solves index-key distribution. Both must match the query contract. Lesson 3 adds the time dimension: even a good key/index design can suffer if a new collection or migration receives full production traffic before the storage layer has time to adapt.

Knowledge check

1. Does every timestamp field impose a 500 writes/s limit in Standard Native?
2. Why not sort by timestamp encoded in the document ID?
3. When is an index exemption safe?
4. What does timestamp sharding trade?
5. How does Enterprise change the problem?

Summary

AtlasMart now treats document IDs and indexed field values as separate key spaces. Scattered IDs prevent one class of moving hotspot; disciplined indexing or sharded required indexes address another.

Authoritative references

• Understand reads and writes at scale
• Firestore best practices
• Standard index overview and indexing best practices
• Sharded timestamps
• Key Visualizer overview
• Key Visualizer document-key patterns
• Enterprise Native Core/Pipeline overview
• Enterprise Native index overview
• Enterprise latency troubleshooting
• Firestore quotas and limits
• Firebase current releases
• Firebase Admin Node.js SDK release notes