Cursor ve offset sayfalama arasındaki fark nedir?
Offset sayfalama, sonuç listesinin başından belirli sayıda satırı atlar. Cursor sayfalama ise önceki sayfanın bıraktığı sıralama konumundan devam eder. API tasarımında seçim, kullanıcının sayfa numarasına mı yoksa kesintisiz bir akışa mı ihtiyaç duyduğuyla başlamalıdır.
Bir yönetim tablosunda doğrudan beşinci sayfaya gitmek yararlı olabilir. Sürekli yeni siparişlerin geldiği bir akışta ise "son gördüğüm kayıttan devam et" davranışı daha doğal olabilir. Aynı arayüz kararının veritabanında farklı maliyetleri vardır.
Buradaki cursor, API'nin taşıdığı devam bilgisidir; SQL'in DECLARE CURSOR komutuyla açılan sunucu nesnesiyle aynı kavram değildir.
Büyük OFFSET değerleri neden pahalı olabilir?
Büyük OFFSET, atlanacak satırların da sunucu tarafından hesaplanmasını gerektirebilir. PostgreSQL LIMIT/OFFSET belgesi, bu nedenle yüksek offset değerlerinin verimsiz olabileceğini belirtir.
Örneğin şu sorgu yirmi satır döndürürken önce yüz bin satırlık konumu geçmeye çalışır. Bu sayı bir performans ölçümü değil, derin sayfayı temsil eden örnek bir parametredir:
SELECT id, created_at
FROM orders_demo
WHERE tenant_id = 42
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 100000;
Veri değişiyorsa başka bir sorun da oluşabilir. İlk sayfa 105, 104, 103 kimliklerini göstersin. Araya 106 eklendikten sonra üç satır atlamak, ikinci sayfanın yeniden 103 ile başlamasına yol açabilir. Kullanıcı aynı kaydı iki kez görür.
Küçük ve nispeten sabit listelerde offset yine kullanışlıdır. Her API'yi cursor modeline geçirmek yerine arayüzün doğrudan sayfa atlama ihtiyacını ve gerçek sorgu yükünü birlikte değerlendirin.
Cursor için neden tek bir tarih alanı yetmez?
Cursor sayfalama, satırları benzersiz bir sıraya koyan anahtarlara ihtiyaç duyar. Aynı created_at değerine sahip kayıtlar varsa yalnızca tarihle devam etmek bazı kayıtları atlatabilir. Tarihin yanına benzersiz id eklemek bu örnekte eşitliği çözer.
created_at ve id alanlarının boş değer almamasını da sağlayın. PostgreSQL satır karşılaştırmaları, küçük/büyük karşılaştırmalarında alanların soldan sağa ele alındığını ve null değerlerin sonucu etkileyebildiğini açıklar.
Sıralama alanları sonradan değiştirilebiliyorsa kaydın listedeki yeri de değişebilir. Bu nedenle devam anahtarını seçmek, sadece bir token biçimi seçmekten daha geniş bir veri modelleme kararıdır.
Sonraki sayfa SQL ile nasıl alınır?
İki alanı da azalan sıralanan bu örnekte, sonraki sayfa son dönen kaydın tarih ve kimlik çiftinden küçük olan satırlardır. orders_demo tablosunda id alanının benzersiz, created_at alanının timestamptz ve ikisinin de NOT NULL olduğunu varsayalım:
SELECT id, created_at
FROM orders_demo
WHERE tenant_id = 42
AND (created_at, id) < (
TIMESTAMPTZ '2026-10-28 08:30:00+00',
901
)
ORDER BY created_at DESC, id DESC
LIMIT 21;
Tarih ve 901 değeri, önceki sayfanın son kaydını temsil eden örnek sabitlerdir. Gerçek API'de bunları doğrulanmış cursor bilgisinden alın ve parametreli sorguyla bağlayın.
Sayfa boyutu yirmiyse yirmi bir satır istemek, devam olup olmadığını anlamaya yarar. İlk yirmisini döndürün; sonraki cursor'ı kullanıcıya dönen yirminci kayıttan üretin. Fazladan alınan yirmi birinci kaydı cursor yapmak, o kaydı sonraki sayfada atlatır. İlk istekte ise cursor koşulu olmadan aynı ORDER BY ve LIMIT kullanılır.
Cursor kullanınca indeks ihtiyacı ortadan kalkar mı?
Cursor sayfalama, uygun bir erişim yolu olmadan otomatik hız garantisi vermez. tenant_id filtresiyle tarih ve kimlik sırasını destekleyen bir B-tree indeksi aday olabilir:
CREATE INDEX orders_demo_page_idx
ON orders_demo (tenant_id, created_at DESC, id DESC);
Bu indeks, indeks inceleme yazısındaki örnekle aynı kolonlara sahiptir. Aynı tablo üzerinde iki örneği birleştiriyorsanız aynı amaçla ikinci bir indeks oluşturmayın. İndeks ve sıralama belgesi, erişim yolu ile sıralamanın ilişkisini açıklar.
Sıralama yönleri karışıksa burada gösterilen çift karşılaştırmasını doğrudan kopyalamayın. Koşul, ORDER BY ile aynı sözleşmeyi uygulamalıdır. Önce eşit tarihli birkaç kayıtla hangi satırların döneceğini elle belirleyin, sonra sorguyla karşılaştırın.
Cursor içinde ne saklanmalı ve nasıl doğrulanmalı?
Cursor, devam için gereken sıralama değerlerini ve gerektiğinde filtre ya da sürüm bilgisini taşımalıdır. Base64 ile kodlamak veriyi gizlemez ve doğruluğunu kanıtlamaz. Sunucu token biçimini doğrulamalı, gerektiğinde bütünlük için imza kullanmalıdır.
Hesap veya tenant yetkisini cursor'dan kabul etmeyin; yetkili kapsamı oturumdan belirleyip her sorguya uygulayın. Kullanıcı filtreyi veya sıralamayı değiştirdiğinde eski cursor'ı sessizce yeniden kullanmak yerine ilk sayfadan başlayın.
Cursor da listeyi zaman içinde sabitlemez. Kesin bir rapor çıktısı gerekiyorsa tutarlı bir veri anı veya ayrı dışa aktarma süreci tasarlamak gerekebilir. Webhook idempotency rehberi de benzer biçimde, bir tekniğin hangi garantiyi verip hangisini vermediğini ayırır.
Sık sorulan sorular
Cursor her zaman offset'ten hızlı mı? Hayır. Veri miktarı, filtreler ve uygun indeks belirleyicidir; gerçek sorgu planıyla ölçülmelidir.
Cursor ile doğrudan 50. sayfaya gidilir mi? Bu model doğal olarak ardışık devam içindir. Rastgele sayfa erişimi gerekiyorsa başka bir gezinme tasarımı gerekebilir.
created_at alanı tek başına yeterli mi? Aynı tarihte birden fazla kayıt varsa yeterli değildir. Benzersiz bir eşitlik bozucu anahtar eklenmelidir.
Cursor, değişen verilerde hiçbir kayıt atlanmayacağını garanti eder mi? Hayır. Sıralama alanlarının değişmesi veya kayıtların silinmesi gibi durumlar ayrıca değerlendirilmelidir.

