Klasik pagination sorgusu şöyledir:
SELECT * FROM orders
ORDER BY created_at DESC
LIMIT 20 OFFSET 0;
İkinci sayfa için OFFSET 20, üçüncü sayfa için OFFSET 40.
Basit, anlaşılır ve ilk sayfalarda çok hızlı.
Ama 5000. sayfaya geldiğinizde:
LIMIT 20 OFFSET 100000
Veritabanı 100.020 satırı okur, ilk 100.000 tanesini atar ve 20 tanesini döndürür.
Offset ne kadar büyürse sorgu o kadar yavaşlar. Index olsa bile atlanan satırların yürünmesi gerekir.
Sadece performans problemi değil
Offset pagination’ın ikinci bir problemi daha var: veri değişirken tutarsız sonuç verir.
Kullanıcı birinci sayfayı görüntüledi.
Bu sırada listeye 3 yeni sipariş eklendi.
Kullanıcı ikinci sayfaya geçti.
Birinci sayfanın son 3 kaydı şimdi ikinci sayfanın başında tekrar görünür. Silme durumunda ise tam tersi olur, bazı kayıtlar hiç görünmeden atlanır.
Sonsuz kaydırma kullanan bir feed’de bu, aynı içeriğin iki kez görünmesi demektir.
Keyset pagination
Alternatif yaklaşım “kaç satır atlayacağım?” yerine “en son nerede kaldım?” sorusunu sormaktır.
SELECT * FROM orders
WHERE created_at < :lastSeenCreatedAt
ORDER BY created_at DESC
LIMIT 20;
Uygun bir index varsa veritabanı doğrudan o noktaya gider ve sonraki 20 satırı okur. Birinci sayfa ile milyonuncu sayfa aynı hızda gelir.
Araya yeni kayıt eklenmesi de sonucu bozmaz. Referans noktası bir pozisyon değil, bir değerdir.
Sıralama benzersiz olmalı
Yukarıdaki sorguda gizli bir hata var.
Aynı milisaniyede oluşturulmuş iki sipariş varsa ve sayfa sınırı tam aralarına denk gelirse, biri kaybolabilir.
Sıralama kolonunun benzersiz olması gerekir. Değilse benzersiz bir kolonla birlikte kullanılmalıdır:
SELECT * FROM orders
WHERE (created_at, id) < (:lastCreatedAt, :lastId)
ORDER BY created_at DESC, id DESC
LIMIT 20;
PostgreSQL row value comparison’ı destekler ve (created_at, id) üzerindeki composite index bu sorguyu verimli çalıştırır.
API’de cursor
Bu değerleri client’a ham olarak vermek yerine opaque bir cursor olarak vermek daha iyidir:
{
"items": [...],
"nextCursor": "eyJjIjoiMjAyNi0xMC0xMlQxOT..."
}
Cursor genellikle sıralama değerlerinin base64 ile kodlanmış halidir.
Opaque olmasının avantajı, client’ın içeriğine bağımlı olmamasıdır. Sıralama mantığı veya kolonlar değişirse API sözleşmesi bozulmaz. Client sadece bir sonraki isteğe cursor’ı geri verir.
Kullanıcıların cursor’ı manipüle etmesinden endişe ediliyorsa imzalanabilir. Ama çoğu durumda backend tarafında doğrulamak yeterlidir.
Neyi kaybediyoruz?
Keyset pagination her şeyi çözmez.
“Sayfa 47’ye git” diyemezsiniz. Sadece ileri veya geri gidebilirsiniz.
Toplam sayfa sayısını göstermek için ayrı bir COUNT(*) sorgusu gerekir ve büyük tablolarda bu da pahalıdır.
Benim pratik ayrımım şu:
Admin panellerinde, küçük ve filtrelenmiş listelerde offset pagination gayet yeterli. Kullanıcılar zaten belirli bir sayfaya atlamak istiyor ve veri seti büyük değil.
Feed’ler, aktivite akışları, log ekranları, dışarıya açık API’ler ve büyük tablolar üzerinde export işlemleri için keyset.
Özellikle export işlemlerinde fark çok belirgin. Milyonlarca kaydı offset ile parça parça okuyan bir job, son sayfalara yaklaştıkça dakikalar süren sorgular çalıştırmaya başlar.
Pagination genellikle API tasarımının en sıkıcı kısmı olarak görülür.
Ama tablo büyüdüğünde ilk yavaşlayan endpoint genellikle bir liste endpoint’idir.
