orderBy, limit / limitToLast, startAt / startAfter / endAt / endBefore, and Stable Cursor Pagination

Learning outcomes

AtlasMart can filter products correctly and still ship broken pagination. Two products have the same price, another lacks a ranking field, and new writes can arrive between page requests. This lesson makes ordering and cursor boundaries explicit so “next page” means the same thing to the SDK, the UI, and the test suite.

1. Ordering changes both sequence and membership

Without an explicit order, a Core query returns matching documents in ascending document-ID order. Once AtlasMart adds orderBy("rank"), documents that do not contain rank are excluded. That is not merely sorting; it changes the set of documents eligible for the result. An inequality filter has a related implied ordering/existence effect on the inequality field.

If “unranked” products must appear, model that state intentionally—for example with a sentinel/status field or a separate query/view—instead of assuming missing fields sort to the end.

2. Tie values need a deterministic final key

AtlasMart has three products priced at 99. A scalar cursor startAfter(99) cannot identify which 99-priced product was the final row of the page. The safer contract is either a document snapshot cursor or an explicit total order such as price plus document ID. Firestore indexes also apply a final ordering by document name/path, but writing the tie-breaker explicitly makes the API contract visible and portable in tests.

import { collection, documentId, getDocs, limit, orderBy, query, startAfter } from "firebase/firestore";const items = collection(db, "catalogItems");const first = query(items, orderBy("price","asc"), orderBy(documentId(),"asc"), limit(2));const page1 = await getDocs(first);const last = page1.docs.at(-1);const second = query(items, orderBy("price","asc"), orderBy(documentId(),"asc"), startAfter(last), limit(2));const page2 = await getDocs(second);console.log(page1.docs.map(d=>d.id), page2.docs.map(d=>d.id));

3. Cursor boundary vocabulary

When a cursor uses raw field values, the values must match the orderBy clauses in order. If one field is not unique, add enough fields to identify the intended boundary. A document snapshot is often safer because the SDK extracts the query's ordered values from that document.

4. Deliberately wrong approach: use product name or price as the page token

A UI engineer encodes ?afterPrice=99. Page 1 ends on p-1002, but p-1006 also costs 99. startAfter(99) can skip remaining ties. The repair is a complete ordered tuple—price + documentId—or a document-snapshot-derived cursor when the SDK session retains it. If pagination tokens cross process boundaries, serialize the primitive ordered fields and a stable ID, validate them, and version the token schema.

5. Hands-on lab: pagination under ties and missing fields

mkdir atlasmart-firestore-query-labcd atlasmart-firestore-query-labnpm init -ynpm install firebase@12.19.0 firebase-admin@14.4.0npm install --save-dev firebase-tools@15.30.0 @firebase/rules-unit-testing@5.0.2node --versionnpx firebase --versionnpx firebase emulators:start --only firestore,auth --project demo-atlasmart-firestore

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";import { initializeApp, applicationDefault } from "firebase-admin/app";import { getFirestore, Timestamp } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });const db = getFirestore();const catalog = {  "p-1001": { category:"camera",  price:99,  rating:4.8, tags:["outdoor","camera"], published:true,  rank:10, sellerId:"seller-a" },  "p-1002": { category:"camera",  price:99,  rating:4.5, tags:["studio","camera"],  published:true,  rank:20, sellerId:"seller-a" },  "p-1003": { category:"sensor",  price:49,  rating:4.8, tags:["outdoor","iot"],     published:true,           sellerId:"seller-b" },  "p-1004": { category:"sensor",  price:149, rating:4.1, tags:["industrial","iot"], published:false, rank:null, sellerId:"seller-b" },  "p-1005": { category:"camera",  price:199, rating:4.9, tags:["outdoor","camera"], published:true,  rank:30, sellerId:"seller-c" },  "p-1006": { category:"gateway", price:99,  rating:4.2, tags:["iot"],              published:true,  rank:40, sellerId:"seller-c" }};for (const [id, data] of Object.entries(catalog)) {  await db.collection("catalogItems").doc(id).set({ ...data, updatedAt: Timestamp.fromMillis(1760000000000) });}const orders = [  ["u-alice","o-1001",{ ownerUid:"u-alice", tenantId:"seller-a", status:"paid",    total:198, createdAt:Timestamp.fromMillis(1760000100000) }],  ["u-alice","o-1002",{ ownerUid:"u-alice", tenantId:"seller-b", status:"shipped", total:49,  createdAt:Timestamp.fromMillis(1760000200000) }],  ["u-bob",  "o-1003",{ ownerUid:"u-bob",   tenantId:"seller-a", status:"paid",    total:99,  createdAt:Timestamp.fromMillis(1760000300000) }]];for (const [uid,id,data] of orders) await db.doc(`users/${uid}/orders/${id}`).set(data);console.log("seeded", Object.keys(catalog).length, "catalog items and", orders.length, "orders");

import assert from "node:assert/strict";import { initializeApp } from "firebase/app";import { collection, connectFirestoreEmulator, documentId, getDocs, getFirestore, limit, orderBy, query, startAfter } from "firebase/firestore";const app=initializeApp({projectId:"demo-atlasmart-firestore",apiKey:"demo",appId:"demo"});const db=getFirestore(app); connectFirestoreEmulator(db,"127.0.0.1",8080);const c=collection(db,"catalogItems");const base=[orderBy("price","asc"),orderBy(documentId(),"asc")];const p1=await getDocs(query(c,...base,limit(3)));const p2=await getDocs(query(c,...base,startAfter(p1.docs.at(-1)),limit(3)));const all=[...p1.docs,...p2.docs].map(d=>d.id);assert.equal(new Set(all).size, all.length);assert.deepEqual(all,["p-1003","p-1001","p-1002","p-1006","p-1004","p-1005"]);console.log("stable two-page traversal",all);

Next, run orderBy("rank") and prove p-1003 disappears because the field is missing. Add an explicit rank/sentinel in a reset fixture and prove it becomes queryable. Finally, insert a new 99-priced product between page requests and record whether the UI's chosen pagination contract tolerates the changed membership.

Production judgment

Choose ordering fields because they represent product semantics, not because a UI component happened to need a sort. Stable pagination is easiest when ordered fields are immutable, fully populated, indexed, authorized, and uniquely tie-broken. If the result must be a historical snapshot, ordinary cursors are the wrong abstraction.

Knowledge check

1. Why can orderBy("rank") remove a matching document?
2. Why is startAfter(99) unsafe when many documents have price 99?
3. What is the difference between startAt and startAfter?
4. What does a document-snapshot cursor not guarantee?
5. When should AtlasMart prefer an immutable composite cursor key?

Summary and next step

AtlasMart now has deterministic local pagination. Lesson 3 expands the query scope from one collection to every same-named subcollection using collection-group queries—and makes the corresponding index and Security Rules scope explicit.

Authoritative references

• Perform simple and compound queries in Cloud Firestore — Current Core filter/operator behavior and Standard-edition limitations.
• Order and limit data with Cloud Firestore — Ordering, limits, field-existence effect, and limit semantics.
• Paginate data with query cursors — Cursor boundaries and document-snapshot pagination.
• Index types in Cloud Firestore — Index scopes, implicit document-name ordering, and query/index execution model.
• Securely query data — Why Security Rules are not filters and collection-group rule requirements.
• Firebase release notes — Current SDK/tooling versions used for the pinned lab baseline.