📚 धडा 08 — Pagination आणि filtering: "पुढचे 20, कृपया"

📍 तुम्ही इथे आहात: 12 पैकी धडा 08 · मागे: lesson-07-errors-idempotency · पुढे: lesson-09-versioning

📦 या ब्रँचमध्ये काय आहे

धडे 01–07, आणि त्यासोबत दहा हजार drawers असलेले कपाट counter कसे सोपवतो: filter → sort → paginate, आणि वाढत जाणाऱ्या कोणत्याही गोष्टीवर cursors offsets पेक्षा सरस का ठरतात.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

Clerk कडे कोणीच "सगळे विद्यार्थी" मागत नाही. तुम्ही पुढचे थोडे मागता: ?limit=2. Clerk दोन drawers आणि एक खूण (bookmark) देतो — next_cursor: 2, "मी id 2 नंतर थांबलो". पुढच्या वेळी तुम्ही ?limit=2&cursor=2 म्हणता आणि त्या खुणेच्या नंतरचे दोन मिळतात. जेव्हा खूण null म्हणून परत येते, तेव्हा कपाट संपले.

"पान 7" ऐवजी खूण का? कारण तुम्ही वाचत असताना कपाट वाढत असते. तुम्ही पान 3 वर असताना नवीन विद्यार्थी नोंदला गेला तर, "पान 4" आता एक drawer आधी सुरू होते — दिशेनुसार, तुम्हाला एक drawer दोनदा दिसतो आणि काही सुटत नाही, किंवा एक सुटतो आणि काहीच दोनदा दिसत नाही. खूण ("id 2 नंतर") तिच्यापुढे drawers जोडले तरी हलत नाही.

Paginate करण्याआधी clerk आणखी दोन slips स्वीकारतो: filter (?class=3A — फक्त तो वर्ग) आणि sort (?sort=name). क्रम नेहमी तोच: आधी filter, मग sort, मग पुढचे थोडे घ्या.

🗺️ आकृती

flowchart LR
    all["🗄️ all students"] -->|"1 filter ?class=3A"| f["3 students"]
    f -->|"2 sort ?sort=name"| s["Aishwarya, Dipika, Katrina"]
    s -->|"3 paginate ?limit=2"| p1["page: Aishwarya, Dipika<br/>next_cursor: 2"]
    p1 -.->|"4 ?cursor=2"| p2["page: Katrina<br/>next_cursor: null"]

❓ काय

Response आकार: {"items": [...], "next_cursor": …|null, "total": N}. total ऐच्छिक आहे आणि मोठ्या tables वर महाग पडू शकतो — अनेक APIs तो वगळतात किंवा अंदाजे देतात.
Cursor: "मी कुठे थांबलो" हे साठवणारा अपारदर्शक token. आमचा cursor म्हणजे शेवटचा id (शिकण्यासाठी, वाचता येणारा); खरे APIs (sort key, id) base64 मध्ये encode करतात, म्हणजे तो कोणत्याही sort क्रमासाठी चालतो.
Offset (?page=7&size=20 → OFFSET 120): सोपा, "पान 7 वर उडी मारा" करू देतो, पण नवीन rows आल्यावर rows सोडतो किंवा दोनदा देतो आणि जितके खोल जाल तितका मंद होतो (database 120 rows सोडण्यासाठी त्या मोजतो).
Limit ला नेहमी कमाल मर्यादा असते (आमची 100 वर थांबते) — नाहीतर ?limit=1000000 ही denial-of-service slip ठरते.
Filters आणि sorts allow-list केलेले असायला हवेत (sort ∈ {id, name, grade}) — client ची string कधीच थेट query मध्ये टाकू नका.

🤔 का

कारण "सगळे परत द्या" 50 rows साठी ठीक आहे आणि 50,000 साठी घातक: timeouts, memory, आणि कायम spinner फिरवत बसलेले mobile apps. आणि कारण वाढत्या यादीचा bug tests मध्ये अदृश्य असतो (unit test चालू असताना tables वाढत नाहीत) आणि production मध्ये उघड दिसतो (items पुन्हा दाखवणारा feed). Cursors ची किंमत एक जादा संकल्पना आहे आणि ते bugs चा एक पूर्ण वर्ग काढून टाकतात.

🔧 कसे (या repo मध्ये)

school_api.py मधले list_students(): class नुसार filter, allow-list केलेला sort, 100 वर मर्यादित limit, आणि id नुसार sort करताना id वर cursor (दुसऱ्या field नुसार sort करताना offset — हे जाणूनबुजून केलेले सोपेपण आहे; खरे APIs ते कसे सर्वसाधारण करतात ते "काय" विभाग सांगतो).

🧪 करून पाहा

B=http://127.0.0.1:8080/v1; K='X-API-Key: hall-pass-123'; J='Content-Type: application/json'
curl -s "$B/students?limit=2"                    # page 1 → next_cursor 2
curl -s "$B/students?limit=2&cursor=2"           # page 2 → next_cursor 4
curl -s "$B/students?limit=2&cursor=4"           # page 3 → next_cursor null
# the growing-list experiment: start paging, insert, keep paging — the cursor does not skip
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}' > /dev/null
curl -s "$B/students?limit=2&cursor=4"           # still starts after id 4 — Zoya appears at the end, once
curl -s "$B/students?class=3A&sort=name&limit=10"
curl -s "$B/students?limit=999999" | head -c 200 # capped, not exploded

✅ तपासा — तुम्हाला काय दिसायला हवे

दोन-दोनची तीन पाने, मग next_cursor: null; नवीन नोंदीनंतर, cursor=4 पासून paging केल्यावर नवीन विद्यार्थी शेवटी नेमका एकदाच दिसतो. Class filter नावानुसार sort केलेले तीन 3A विद्यार्थी परत देतो; प्रचंड limit जास्तीत जास्त 100 items परत देतो.

🏁 तुम्ही आत्ताच काय सिद्ध केले

Filter → sort → paginate, नवीन नोंदींनंतरही टिकणाऱ्या खुणेसह — आणि counter चे संरक्षण करणारी मर्यादा.

⚠️ नेहमीच्या चुका

limit ला कमाल मर्यादा नसणे
feed किंवा log वर offset pagination (rows सुटतात आणि दोनदा येतात)
client सांगेल त्या कोणत्याही field नुसार sort करणे — ते allow-list करा (SQL injection आणि मंद queries इथेच लपतात)
प्रचंड table च्या प्रत्येक पानावर संपूर्ण table मोजून total परत देणे
versions दरम्यान cursor चा अर्थ बदलणे — तो contract चा भाग आहे (अपारदर्शक असला तरी)

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: infinite-scroll feed वरचे प्रत्येक "app ने तो item दोनदा का दाखवला?" ticket म्हणजे offset pagination. Index असलेल्या column वरच्या cursors मुळेच मोठे feeds scale होतात — Database school चा धडा 06 या गोष्टीचा index वाला अर्धा भाग आहे.

⏭️ पुढे

Counter आधीपासून वापरणाऱ्या apps ना न मोडता बदलायला हवा: versioning — additive बदल, /v2, deprecation आणि sunset.

git checkout lesson-09-versioning

📚 Lesson 08 — Pagination & filtering: "the next 20, please"

📍 You are here: Lesson 08 of 12 · Previous: lesson-07-errors-idempotency · Next: lesson-09-versioning

📦 What's in this branch

Lessons 01–07, plus how a counter hands over a cabinet with ten thousand drawers: filter → sort → paginate, and why cursors beat offsets on anything that grows.

🧒 Explain like I'm 5

Nobody asks the clerk for "all the students". You ask for the next few: ?limit=2. The clerk hands over two drawers and a bookmark — next_cursor: 2, "I stopped after id 2". Next time you say ?limit=2&cursor=2 and get the two after that bookmark. When the bookmark comes back null, the cabinet is finished.

Why a bookmark instead of "page 7"? Because the cabinet grows while you read it. If a new student is filed while you are on page 3, "page 4" now starts one drawer earlier — you see one drawer twice and miss nothing, or miss one and see nothing twice, depending on the direction. A bookmark ("after id 2") does not move when drawers are added in front of it.

Two more slips the clerk accepts before paginating: filter (?class=3A — only that class) and sort (?sort=name). The order is always the same: filter, then sort, then take the next few.

🗺️ Diagram

flowchart LR
    all["🗄️ all students"] -->|"1 filter ?class=3A"| f["3 students"]
    f -->|"2 sort ?sort=name"| s["Aishwarya, Dipika, Katrina"]
    s -->|"3 paginate ?limit=2"| p1["page: Aishwarya, Dipika<br/>next_cursor: 2"]
    p1 -.->|"4 ?cursor=2"| p2["page: Katrina<br/>next_cursor: null"]

❓ What

Response shape: {"items": [...], "next_cursor": …|null, "total": N}. total is optional and can be expensive on big tables — many APIs omit it or make it approximate.
Cursor: an opaque token that encodes "where I stopped". Ours is the last id (readable, for learning); real APIs base64-encode (sort key, id) so it works for any sort order.
Offset (?page=7&size=20 → OFFSET 120): simple, allows "jump to page 7", but skips or duplicates rows under inserts and gets slower the deeper you go (the database counts 120 rows to skip them).
Limit always has a maximum (ours caps at 100) — otherwise ?limit=1000000 is a denial-of-service slip.
Filters and sorts must be allow-listed (sort ∈ {id, name, grade}) — never pass a client string straight into a query.

🤔 Why

Because "return everything" is fine for 50 rows and fatal for 50,000: timeouts, memory, and mobile apps rendering a spinner forever. And because the growing-list bug is invisible in tests (tables do not grow during a unit test) and obvious in production (a feed that repeats items). Cursors cost one extra concept and remove a whole class of bugs.

🔧 How (in this repo)

list_students() in school_api.py: filter by class, allow-listed sort, limit capped at 100, and a cursor on id when sorting by id (an offset when sorting by another field — a deliberate simplification; the What section says how real APIs generalise it).

🧪 Try it

B=http://127.0.0.1:8080/v1; K='X-API-Key: hall-pass-123'; J='Content-Type: application/json'
curl -s "$B/students?limit=2"                    # page 1 → next_cursor 2
curl -s "$B/students?limit=2&cursor=2"           # page 2 → next_cursor 4
curl -s "$B/students?limit=2&cursor=4"           # page 3 → next_cursor null
# the growing-list experiment: start paging, insert, keep paging — the cursor does not skip
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}' > /dev/null
curl -s "$B/students?limit=2&cursor=4"           # still starts after id 4 — Zoya appears at the end, once
curl -s "$B/students?class=3A&sort=name&limit=10"
curl -s "$B/students?limit=999999" | head -c 200 # capped, not exploded

✅ Verify — what you should see

Three pages of two, then next_cursor: null; after the insert, paging from cursor=4 shows the new student exactly once at the end. The class filter returns three 3A students sorted by name; the huge limit returns at most 100 items.

🏁 What you just proved

Filter → sort → paginate, with a bookmark that survives inserts — and a cap that protects the counter.

⚠️ Common mistakes

no maximum on limit
offset pagination on a feed or log (skips and duplicates)
sorting by any field the client names — allow-list it (SQL injection and slow queries hide here)
returning total from a full table count on every page of a huge table
changing the cursor's meaning between versions — it is part of the contract (even if opaque)

🏭 Why this matters in production: every "why did the app show that item twice?" ticket on an infinite-scroll feed is offset pagination. Cursors on an indexed column are how the big feeds scale — the Database school's lesson 06 is the index half of this story.

⏭️ Next

The counter must change without breaking the apps that already use it: versioning — additive changes, /v2, deprecation and sunset.

git checkout lesson-09-versioning

← Previouserrors idempotency Next →versioning

This page is the lesson's README from the lesson-08-pagination-filtering branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.