Cursor Pagination بالعربي: ليه OFFSET بيبطأ مع كل صفحة جديدة

ملاحظة حاسمة: لازم تعمل index مركّب على (created_at DESC, id DESC) بنفس ترتيب الـ ORDER BY، عشان الـ tuple comparison تستخدم الـ index. من غير الـ index ده، كل اللي هيحصل إن المقارنة هتتعمل row-by-row وهترجع تبطأ من تاني.

التطبيق في Node.js مع pg

الطريقة المعيارية إن الـ cursor بيتبعت للعميل كـ string مُشفّر بـ base64. ده بيخفي التفاصيل الداخلية (ما حدش لازم يعرف إن الـ cursor هو created_at + id)، وبيخلّيك تغيّر شكله لاحقًا من غير ما تكسر الـ API.

العميل بيبعت أول طلب بدون cursor، ويستلم nextCursor. الطلب اللي بعده بيبعت الـ cursor ده، وهكذا. لما الـ nextCursor يرجع null، دي نهاية البيانات.

الأرقام: قياس فعلي على جدول 10 مليون صف

الأرقام دي من benchmark فعلي على PostgreSQL 16، جدول articles بـ 10 مليون صف، index مركّب على (created_at DESC, id DESC)، سيرفر بـ 8 cores و 16GB RAM. الأرقام متوسط 100 طلب:

• صفحة 1 (OFFSET 0) → 3ms
• صفحة 100 (OFFSET 2,000) → 18ms
• صفحة 5,000 (OFFSET 100,000) → 220ms
• صفحة 50,000 (OFFSET 1,000,000) → 1,800ms (timeout في كتير من الـ APIs)
• Cursor في أي مكان في الجدول → 2 إلى 4ms ثابت

ده معناه إن OFFSET 1,000,000 أبطأ 600 مرة من Cursor. ومش قصة CPU بس — الـ DB بتاكل buffer cache وبتطرد صفحات مهمة تانية، فالـ queries التانية بتبطأ كمان. ده اللي بيخلي الـ deep pagination سبب رئيسي في "السيرفر فجأة بطيء الساعة 3 الصبح".

trade-offs لازم تعرفها

بتكسب: أداء ثابت بغض النظر عن عمق الصفحة. صحة بيانات أعلى — لو حد أضاف سجل جديد وانت بتتصفح، OFFSET بيدّيك نفس السجل مرتين أو يتخطى واحد؛ Cursor بيحافظ على الترتيب لأنه مرتبط بقيمة فعلية مش برقم صفحة.

بتخسر: ما تقدرش تقفز لصفحة عشوائية. لو المستخدم ضغط "اذهب لصفحة 47" لازم يمر على 46 قبلها. كمان ما تقدرش تعرض "صفحة 4 من 120" من غير ما تعمل COUNT(*) منفصل (وده بطيء لوحده على الجداول الكبيرة). Cursor الأنسب لـ infinite scroll و "Load More"، مش لـ classical numbered pagination.

متى لا تستخدم Cursor Pagination

هذا الشرح مبني على فرضية إن المستخدم بيتصفح بالترتيب. الحالات اللي Cursor مش مناسب فيها:

• Dashboards إدارية فيها "اذهب لصفحة X" — لو الجدول أقل من 100,000 صف، OFFSET مقبول جدًا وأبسط.
• UI محتاج عدد الصفحات الكلي — محتاج COUNT على كل الأحوال، فالـ cursor مش بيوفّر كتير.
• ترتيب متغيّر بناء على فلتر ديناميكي — كل ترتيب محتاج index مركّب خاص به. ممكن تلاقي نفسك بـ 8 indexes على نفس الجدول.
• جدول أقل من مليون صف — الفرق مش هيبان كتير، والـ OFFSET أبسط للتطوير والـ debugging.

المصادر

• PostgreSQL Documentation — LIMIT and OFFSET: postgresql.org/docs/current/queries-limit.html
• Use The Index, Luke — Paging Through Results (Markus Winand): use-the-index-luke.com/no-offset
• Slack Engineering — Evolving API Pagination at Slack: slack.engineering/evolving-api-pagination-at-slack
• Shopify Engineering — Pagination at Shopify: shopify.engineering/pagination-relative-cursors
• GitLab Docs — Keyset Pagination: docs.gitlab.com/ee/development/database/keyset_pagination.html

الخطوة التالية

افتح أبطأ endpoint عندك فيه pagination، وشوف في الـ logs كام ms بياخد في الصفحات الأخيرة مقارنة بالأولى. لو الفرق بين صفحة 1 وصفحة 100 أكبر من 10×، حوّل الـ endpoint ده لـ cursor. ابدأ بالـ index المركّب قبل ما تلمس كود الـ API — في نص الحالات الـ index لوحده بيحل المشكلة مؤقتًا وبيديك وقت تغيّر الكود براحتك.