Pagination kursor vs offset untuk API layar admin yang cepat

Mengapa pagination bisa membuat layar admin terasa lambat

Layar admin sering dimulai sebagai tabel sederhana: muat 25 baris pertama, tambahkan kotak pencarian, selesai. Terasa instan dengan beberapa ratus record. Lalu datanya tumbuh, dan layar yang sama mulai tersendat.

Masalah biasanya bukan pada UI. Melainkan apa yang harus dilakukan API sebelum dapat mengembalikan halaman 12 dengan sorting dan filter diterapkan. Saat tabel membesar, backend menghabiskan lebih banyak waktu mencari kecocokan, menghitungnya, dan melewati hasil sebelumnya. Jika setiap klik memicu kueri yang lebih berat, layar terasa seperti sedang berpikir bukan merespons.

Anda cenderung memperhatikannya pada situasi yang sama: pergantian halaman semakin lambat, sorting jadi lesu, pencarian terasa tidak konsisten antar halaman, dan infinite scroll memuat dengan lonjakan (cepat, lalu tiba-tiba lambat). Dalam sistem sibuk Anda bahkan mungkin melihat duplikat atau baris yang hilang ketika data berubah di antara permintaan.

UI web dan mobile juga mendorong pagination ke arah berbeda. Tabel admin web mendorong pengguna untuk melompat ke halaman tertentu dan menyortir berdasarkan banyak kolom. Layar mobile biasanya menggunakan daftar tak berujung yang memuat potongan berikutnya, dan pengguna mengharapkan setiap pengambilan sama cepatnya. Jika API Anda dibangun hanya berdasarkan nomor halaman, mobile sering menderita. Jika hanya berdasarkan next/after, tabel web bisa terasa terbatas.

Tujuannya bukan sekadar mengembalikan 25 item. Tapi paging yang cepat, dapat diprediksi, dan tetap stabil saat data tumbuh, dengan aturan yang bekerja sama untuk tabel dan daftar tak berujung.

Dasar-dasar pagination yang bergantung pada UI Anda

Pagination adalah memecah daftar panjang menjadi potongan lebih kecil agar layar bisa memuat dan merender cepat. Alih-alih meminta API untuk setiap record, UI meminta irisan hasil berikutnya.

Kontrol terpenting adalah ukuran halaman (sering disebut limit). Halaman yang lebih kecil biasanya terasa lebih cepat karena server melakukan lebih sedikit kerja dan aplikasi menggambar lebih sedikit baris. Tapi halaman yang terlalu kecil bisa terasa lompat-lompat karena pengguna harus klik atau scroll lebih sering. Untuk banyak tabel admin, 25 sampai 100 item adalah rentang praktis, dengan mobile biasanya memilih ujung bawah.

Urutan sortir yang stabil lebih penting daripada yang banyak tim duga. Jika urutan bisa berubah antar permintaan, pengguna melihat duplikat atau baris yang hilang saat paging. Sortir stabil biasanya berarti mengurutkan berdasarkan field utama (seperti created_at) plus tie-breaker (seperti id). Ini penting baik Anda menggunakan offset maupun kursor.

Dari sudut klien, respons paginasi harus menyertakan items, petunjuk halaman berikutnya (nomor halaman atau token kursor), dan hanya jumlah yang benar-benar dibutuhkan UI. Beberapa layar membutuhkan total tepat untuk “1-50 dari 12.340”. Yang lain hanya butuh has_more.

Offset pagination: cara kerjanya dan di mana ia menyulitkan

Offset pagination adalah pendekatan klasik halaman N. Klien meminta sejumlah baris tetap dan memberi tahu API berapa banyak baris yang harus dilewati terlebih dahulu. Anda akan melihatnya sebagai limit dan offset, atau sebagai page dan pageSize yang dikonversi server ke offset.

Contoh permintaan tipikal terlihat seperti ini:

• GET /tickets?limit=50\u0026offset=950
• “Berikan saya 50 tiket, lewati 950 pertama.”

Ini cocok dengan kebutuhan admin umum: lompat ke halaman 20, menelusuri record lama, atau mengekspor daftar besar dalam potongan. Juga mudah dibicarakan secara internal: “Lihat halaman 3 dan Anda akan melihatnya.”

Masalah muncul pada halaman yang dalam. Banyak database masih harus berjalan melewati baris yang dilewati sebelum mengembalikan halaman Anda, terutama ketika urutan sortir tidak didukung oleh indeks yang ketat. Halaman 1 mungkin cepat, tapi halaman 200 bisa menjadi terasa lambat, yang persis membuat layar admin terasa lag saat pengguna scroll atau melompat.

Masalah lain adalah konsistensi saat data berubah. Bayangkan seorang manajer support membuka halaman 5 tiket yang disortir berdasarkan yang terbaru. Sementara mereka melihat, tiket baru tiba atau tiket lama dihapus. Penyisipan bisa mendorong item maju (duplikat antar halaman). Penghapusan bisa mendorong item mundur (record menghilang dari jalur penelusuran pengguna).

Offset pagination masih bisa baik untuk tabel kecil, dataset yang stabil, atau ekspor satu kali. Pada tabel besar dan aktif, kasus tepi muncul dengan cepat.

Cursor pagination: cara kerjanya dan mengapa ia tetap stabil

Cursor pagination menggunakan kursor sebagai penanda. Alih-alih mengatakan “berikan saya halaman 7,” klien mengatakan “lanjutkan setelah item ini.” Kursor biasanya menyandikan nilai sortir item terakhir (misalnya created_at dan id) sehingga server bisa melanjutkan dari tempat yang tepat.

Permintaan biasanya hanya berisi:

• limit: berapa banyak item yang dikembalikan
• cursor: token opaque dari respons sebelumnya (sering disebut after)

Respons mengembalikan items plus kursor baru yang menunjuk ke akhir irisan itu. Perbedaan praktisnya adalah kursor tidak meminta database menghitung dan melewati baris. Mereka memintanya untuk mulai dari posisi yang diketahui.

Itulah sebabnya pagination kursor tetap cepat untuk daftar yang digulir maju. Dengan indeks yang baik, database bisa lompat ke “item setelah X” dan kemudian membaca limit baris berikutnya. Dengan offset, server sering harus memindai (atau setidaknya melewati) lebih banyak baris seiring offset bertambah.

Dari perilaku UI, pagination kursor membuat “Next” menjadi alami: ambil kursor yang dikembalikan dan kirimkan kembali pada permintaan berikutnya. “Previous” bersifat opsional dan lebih rumit. Beberapa API mendukung kursor before, sementara yang lain mengambil dalam urutan terbalik lalu membalik hasil.

Kapan memilih kursor, offset, atau hybrid

Pilihan dimulai dari bagaimana orang benar-benar menggunakan daftar.

Pagination kursor paling cocok ketika pengguna sebagian besar bergerak maju dan kecepatan adalah prioritas: activity log, chat, pesanan, tiket, jejak audit, dan sebagian besar infinite scroll mobile. Ia juga berperilaku lebih baik ketika baris baru disisipkan atau dihapus saat seseorang menelusuri.

Offset pagination masuk akal ketika pengguna sering melompat-lompat: tabel admin klasik dengan nomor halaman, go-to-page, dan navigasi cepat bolak-balik. Mudah dijelaskan, tetapi bisa menjadi lebih lambat pada dataset besar dan kurang stabil saat data berubah di bawah Anda.

Cara praktis memutuskan:

• Pilih kursor ketika aksi utama adalah “selanjutnya, selanjutnya, selanjutnya.”
• Pilih offset ketika “lompat ke halaman N” benar-benar diperlukan.
• Anggap totals sebagai opsional. Menghitung total yang akurat bisa mahal pada tabel yang sangat besar.

Hybrid umum digunakan. Satu pendekatan adalah next/prev berbasis kursor untuk kecepatan, plus mode lompat-halaman opsional untuk subset yang kecil dan difilter di mana offset tetap cepat. Pendekatan lain adalah pengambilan berbasis kursor dengan nomor halaman berdasarkan snapshot cache, sehingga tabel terasa familier tanpa mengubah setiap permintaan menjadi kerja berat.

Kontrak API konsisten yang bekerja di web dan mobile

Layar admin terasa lebih cepat ketika setiap endpoint daftar berperilaku sama. UI bisa berubah (tabel web dengan nomor halaman, daftar tak berujung mobile), tetapi kontrak API harus tetap stabil sehingga Anda tidak perlu belajar ulang aturan pagination untuk setiap layar.

Kontrak praktis memiliki tiga bagian: rows, state paging, dan totals opsional. Pertahankan nama yang identik di seluruh endpoint (tickets, users, orders), meskipun mode paging yang mendasarinya berbeda.

Berikut bentuk respons yang bekerja baik untuk web dan mobile:

{
  "data": [ { "id": "...", "createdAt": "..." } ],
  "page": {
    "mode": "cursor",
    "limit": 50,
    "nextCursor": "...",
    "prevCursor": null,
    "hasNext": true,
    "hasPrev": false
  },
  "totals": {
    "count": 12345,
    "filteredCount": 120
  }
}

Beberapa detail membuat ini mudah digunakan kembali:

• page.mode memberi tahu klien apa yang dilakukan server tanpa mengubah nama field.
• limit selalu ukuran halaman yang diminta.
• nextCursor dan prevCursor ada walau salah satunya null.
• totals bersifat opsional. Jika mahal, kembalikan hanya ketika klien memintanya.

Tabel web masih bisa menampilkan “Halaman 3” dengan menjaga indeks halamannya sendiri dan memanggil API berulang kali. Daftar mobile bisa mengabaikan nomor halaman dan sekadar meminta potongan berikutnya.

Jika Anda membangun kedua UI web dan mobile admin di AppMaster, kontrak stabil seperti ini cepat memberi manfaat. Perilaku daftar yang sama dapat digunakan ulang di berbagai layar tanpa logika pagination khusus per endpoint.

Aturan sorting yang menjaga pagination stabil

Sorting adalah tempat pagination biasanya rusak. Jika urutan bisa berubah antar permintaan, pengguna melihat duplikat, celah, atau baris yang “hilang.”

Jadikan sorting sebagai kontrak, bukan sekadar saran. Publikasikan field sortir dan arah yang diizinkan, dan tolak yang lain. Itu menjaga API Anda bisa diprediksi dan mencegah klien meminta sort lambat yang terlihat aman di pengembangan.

Sortir yang stabil memerlukan tie-breaker unik. Jika Anda mengurutkan berdasarkan created_at dan dua record memiliki timestamp yang sama, tambahkan id (atau kolom unik lain) sebagai kunci sortir terakhir. Tanpanya, database bebas mengembalikan nilai yang sama dalam urutan apa pun.

Aturan praktis yang tahan lama:

• Izinkan sorting hanya pada field yang diindeks dan terdefinisi jelas (misalnya created_at, updated_at, status, priority).
• Selalu sertakan tie-breaker unik sebagai kunci terakhir (misalnya id ASC).
• Tentukan sortir default (misalnya created_at DESC, id DESC) dan pertahankan konsistensinya di seluruh klien.
• Dokumentasikan bagaimana null diurutkan (misalnya “nulls last” untuk tanggal dan angka).

Sorting juga memengaruhi pembuatan kursor. Kursor harus menyandikan nilai sortir item terakhir secara berurutan, termasuk tie-breaker, sehingga halaman berikutnya dapat menanyakan “after” tuple itu. Jika sortir berubah, kursor lama menjadi tidak valid. Anggap parameter sortir sebagai bagian dari kontrak kursor.

Filter dan totals tanpa merusak kontrak

Filter harus terasa terpisah dari pagination. UI mengatakan, “tunjukkan kumpulan baris yang berbeda,” dan baru kemudian meminta, “page melalui kumpulan itu.” Jika Anda mencampurkan field filter ke token pagination atau memperlakukan filter sebagai opsional dan tidak tervalidasi, Anda mendapatkan perilaku yang sulit di-debug: halaman kosong, duplikat, atau kursor yang tiba-tiba menunjuk ke dataset berbeda.

Aturan sederhana: filter berada di parameter query biasa (atau body request untuk POST), dan kursor bersifat opaque dan hanya berlaku untuk kombinasi filter plus sortir yang persis sama. Jika pengguna mengubah filter (status, rentang tanggal, assignee), klien harus membuang kursor lama dan mulai dari awal.

Bersikap ketat tentang filter yang diizinkan. Itu melindungi performa dan menjaga perilaku tetap dapat diprediksi:

• Tolak field filter yang tidak dikenal (jangan mengabaikannya diam-diam).
• Validasi tipe dan rentang (tanggal, enum, ID).
• Batasi filter yang luas (misalnya, maksimum 50 ID dalam daftar IN).
• Terapkan filter yang sama pada data dan totals (jangan mismatch angka).

Totals adalah tempat banyak API menjadi lambat. Hitungan tepat bisa mahal pada tabel besar, terutama dengan banyak filter. Anda umumnya punya tiga pilihan: tepat, perkiraan, atau tidak ada. Tepat bagus untuk dataset kecil atau ketika pengguna benar-benar butuh “menampilkan 1-25 dari 12.431.” Perkiraan sering cukup untuk layar admin. Tidak ada juga oke ketika Anda hanya butuh “Load more.”

Untuk menghindari memperlambat setiap permintaan, buat totals opsional: hitung hanya ketika klien meminta (misalnya dengan flag seperti includeTotal=true), cache sebentar per set filter, atau kembalikan totals hanya di halaman pertama.

Langkah demi langkah: desain dan implementasi endpoint

Mulailah dengan default. Endpoint daftar butuh urutan sortir yang stabil, plus tie-breaker untuk baris yang berbagi nilai yang sama. Contoh: createdAt DESC, id DESC. Tie-breaker (id) mencegah duplikat dan celah saat record baru ditambahkan.

Tentukan satu bentuk request dan biarkan itu membosankan. Parameter tipikal adalah limit, cursor (atau offset), sort, dan filters. Jika Anda mendukung kedua mode, buat mereka saling eksklusif: klien mengirim cursor, atau mengirim offset, tetapi tidak keduanya.

Pertahankan kontrak respons yang konsisten sehingga UI web dan mobile bisa berbagi logika daftar yang sama:

• items: halaman record
• nextCursor: kursor untuk mengambil halaman berikutnya (atau null)
• hasMore: boolean agar UI bisa memutuskan menampilkan “Load more”
• total: total record yang cocok (null kecuali diminta jika penghitungan mahal)

Implementasi adalah tempat dua pendekatan berbeda.

Query offset biasanya ORDER BY ... LIMIT ... OFFSET ..., yang bisa melambat pada tabel besar.

Query kursor menggunakan kondisi seek berdasarkan item terakhir: “berikan saya item di mana (createdAt, id) kurang dari (createdAt, id) terakhir”. Itu menjaga performa lebih stabil karena database bisa menggunakan indeks.

Sebelum Anda kirim, tambahkan guardrail:

• Batasi limit (misalnya, maks 100) dan tetapkan default.
• Validasi sort terhadap allowlist.
• Validasi filter berdasarkan tipe dan tolak key yang tidak dikenal.
• Buat cursor opaque (sandi nilai sortir terakhir) dan tolak kursor yang salah format.
• Putuskan bagaimana total diminta.

Uji dengan data yang berubah di bawah Anda. Buat dan hapus record di antar permintaan, perbarui field yang memengaruhi sortir, dan verifikasi Anda tidak melihat duplikat atau baris yang hilang.

Contoh: daftar tiket yang tetap cepat di web dan mobile

Tim support membuka layar admin untuk meninjau tiket terbaru. Mereka butuh daftar terasa instan, bahkan saat tiket baru tiba dan agen memperbarui tiket lama.

Di web, UI adalah tabel. Sortir default berdasarkan updated_at (paling baru dulu), dan tim sering memfilter ke Open atau Pending. Endpoint yang sama bisa mendukung kedua tindakan itu dengan sortir stabil dan token kursor.

GET /tickets?status=open\u0026sort=-updated_at\u0026limit=50\u0026cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNi0wMS0yNVQxMTo0NTo0MloiLCJpZCI6IjE2OTMifQ==

Respons tetap dapat diprediksi untuk UI:

{
  "items": [{"id": 1693, "subject": "Login issue", "status": "open", "updated_at": "2026-01-25T11:45:42Z"}],
  "page": {"next_cursor": "...", "has_more": true},
  "meta": {"total": 128}
}

Di mobile, endpoint yang sama memberi daya untuk infinite scroll. Aplikasi memuat 20 tiket sekaligus, lalu mengirim next_cursor untuk mengambil batch berikutnya. Tidak ada logika nomor-halaman, dan lebih sedikit kejutan saat record berubah.

Kuncinya adalah kursor menyandikan posisi terakhir yang terlihat (misalnya updated_at plus id sebagai tie-breaker). Jika sebuah tiket diperbarui saat agen sedang scroll, tiket itu bisa bergerak ke atas pada refresh berikutnya, tetapi tidak akan menyebabkan duplikat atau celah di feed yang sudah digulir.

Totals berguna, tetapi mahal pada dataset besar. Aturan sederhana adalah mengembalikan meta.total hanya ketika pengguna menerapkan filter (misalnya status=open) atau secara eksplisit memintanya.

Kesalahan umum yang menyebabkan duplikat, celah, dan lag

Sebagian besar bug pagination bukan dari database. Mereka muncul dari keputusan API kecil yang terlihat baik di pengujian, lalu runtuh ketika data berubah antar permintaan.

Penyebab paling umum duplikat (atau baris yang hilang) adalah sorting pada field yang tidak unik. Jika Anda menyortir berdasarkan created_at dan dua item memiliki timestamp sama, urutan bisa berubah antar permintaan. Perbaikannya sederhana: selalu tambahkan tie-breaker stabil, biasanya primary key, dan anggap sortir sebagai pasangan seperti (created_at desc, id desc).

Masalah umum lain adalah membiarkan klien meminta ukuran halaman berapa pun. Satu permintaan besar bisa memicu lonjakan CPU, memori, dan waktu respons, yang memperlambat setiap layar admin. Pilih default yang masuk akal dan batas keras, serta kembalikan error saat klien meminta lebih.

Totals juga bisa menyakiti. Menghitung semua baris yang cocok pada setiap permintaan bisa menjadi bagian paling lambat dari endpoint, terutama dengan filter. Jika UI membutuhkan totals, ambil hanya saat diminta (atau kembalikan perkiraan), dan hindari memblokir scrolling daftar pada penghitungan penuh.

Kesalahan yang paling sering menciptakan celah, duplikat, dan lag:

• Sorting tanpa tie-breaker unik (urutan tidak stabil)
• Ukuran halaman tak terbatas (beban server)
• Mengembalikan totals setiap kali (kueri lambat)
• Mencampur aturan offset dan kursor dalam satu endpoint (perilaku klien membingungkan)
• Menggunakan kembali kursor yang sama saat filter atau sortir berubah (hasil salah)

Reset pagination setiap kali filter atau sortir berubah. Anggap filter baru sebagai pencarian baru: bersihkan cursor/offset dan mulai dari halaman pertama.

Daftar periksa cepat sebelum rilis

Jalankan ini sekali dengan API dan UI berdampingan. Sebagian besar masalah terjadi pada kontrak antara layar daftar dan server.

• Sortir default stabil dan menyertakan tie-breaker unik (misalnya created_at DESC, id DESC).
• Field dan arah sortir di-whitelist.
• Ukuran halaman maksimum ditegakkan, dengan default yang masuk akal.
• Token kursor opaque, dan kursor tidak valid gagal dengan cara yang dapat diprediksi.
• Perubahan filter atau sortir mereset state pagination.
• Perilaku totals eksplisit: tepat, perkiraan, atau dihilangkan.
• Kontrak yang sama mendukung tabel dan infinite scroll tanpa kasus khusus.

Langkah berikutnya: standarkan daftar Anda dan jaga konsistensi

Pilih satu daftar admin yang sering digunakan dan jadikan standar emas Anda. Endpoint yang sibuk seperti Tickets, Orders, atau Users adalah titik awal yang baik. Setelah endpoint tersebut terasa cepat dan dapat diprediksi, terapkan kontrak yang sama ke seluruh layar admin Anda.

Tuliskan kontrak itu, walau singkat. Jelaskan apa yang API terima dan kembalikan agar tim UI tidak menebak-nebak dan tanpa sengaja menciptakan aturan berbeda per endpoint.

Standar sederhana untuk setiap endpoint daftar:

• Sort yang diizinkan: nama field persis, arah, dan default yang jelas (plus tie-breaker seperti id).
• Filter yang diizinkan: field mana yang dapat difilter, format nilai, dan apa yang terjadi pada filter tidak valid.
• Perilaku totals: kapan Anda mengembalikan hitungan, kapan mengembalikan “unknown”, dan kapan mengabaikannya.
• Bentuk respons: kunci konsisten (items, info paging, sort/filter yang diterapkan, totals).
• Aturan error: kode status konsisten dan pesan validasi yang dapat dibaca.

Jika Anda membangun layar admin ini dengan AppMaster (appmaster.io), membantu untuk menstandarkan kontrak pagination lebih awal. Anda bisa menggunakan ulang perilaku daftar yang sama di web app dan aplikasi native mobile, sehingga menghabiskan lebih sedikit waktu memperbaiki kasus tepi pagination nantinya.