Redis Hash Alan Süresi: HEXPIRE, HTTL, HPERSIST, HSETEX ve HGETEX

Alan süresi neden gerekli?

Alan süresi gelmeden önce bir hash'in yalnızca tamamına EXPIRE verilebiliyordu. Oysa birçok senaryoda aynı nesnenin bazı parçaları kalıcı, bazıları geçicidir. 7.4 sürüm notu bu özelliğin özellikle önbellek ve oturum saklama senaryolarında bellek verimliliği ve performans sağladığını belirtir. Hash belgeleri dört tipik kullanım sayar:

• Olay takibi: Son bir saatin olaylarını tek bir hash'te tutun, her olaya bir saatlik süre verin; HLEN son bir saatteki olay sayısını verir.
• Dolandırıcılık tespiti: Saatlik olay sayaçlarını alan olarak tutup her alana 48 saat süre verin; hash size son 48 saatin saat saat dağılımını gösterir.
• Müşteri oturum yönetimi: Her oturum için ayrı bir hash anahtarı açın ve müşterinin hash'ine bir oturum alanı ekleyin; oturum bitince hem oturum anahtarının hem de müşteri hash'indeki alanın süresi dolsun.
• Aktif oturum takibi: Bütün aktif oturumları tek bir hash'te tutun, her oturuma hareketsizlik süresi verin; HLEN aktif oturum sayısını döndürür.

Bu senaryoların ortak noktası şudur: eskiyen verileri temizlemek için ayrı bir zamanlanmış görev yazmanız gerekmez, Redis süresi dolan alanları kendisi siler.

HEXPIRE ile alana saniye cinsinden süre vermek

Söz dizimi şu sırayı izler: önce anahtar, sonra süre, isteğe bağlı koşul, ardından FIELDS kelimesi, alan sayısı ve alan adları. Alan sayısını (numfields) yazmayı unutmak ya da gerçek alan sayısıyla uyuşmayan bir değer vermek en sık görülen söz dizimi hatasıdır. Belgelerdeki sensör örneği iki alana 60 saniye verir ve kalan süreyi okur:

> DEL sensor:sensor1
(integer) 0
> HSET sensor:sensor1 air_quality 256 battery_level 89
(integer) 2
> HEXPIRE sensor:sensor1 60 FIELDS 2 air_quality battery_level
1) (integer) 1
2) (integer) 1
> HTTL sensor:sensor1 FIELDS 2 air_quality battery_level
1) (integer) 60
2) (integer) 60

Yanıt bir dizidir ve istediğiniz her alan için ayrı bir kod içerir. Bu kodları doğru okumak, alan süresiyle çalışmanın en önemli parçasıdır:

Belgelerdeki şu örnek kodların karışık geldiği durumu gösterir. Var olan iki alan için 1, hash'te olmayan field3 için -2 döner. Var olmayan bir anahtara NX ile süre vermeye çalışmak da her alan için -2 üretir:

> HEXPIRE no-key 20 NX FIELDS 2 field1 field2
1) (integer) -2
2) (integer) -2
> HSET mykey field1 "hello" field2 "world"
(integer) 2
> HEXPIRE mykey 10 FIELDS 3 field1 field2 field3
1) (integer) 1
2) (integer) 1
3) (integer) -2

Söz dizimi hatası, eksik zorunlu argüman, bilinmeyen argüman ya da aralık dışı değer verdiğinizde komut dizi yerine bir hata yanıtı döndürür. Anahtar var ama hash değilse yine hata alırsınız. Yani -2 kodu "komut çalıştı ama bu alan yok" anlamına gelir, hata ise "komut hiç çalışmadı" demektir.

NX, XX, GT ve LT koşulları

Bu dört seçenek birbirini dışlar ve her alan için ayrı ayrı değerlendirilir. NX yalnızca süresi olmayan alanlara süre verir; XX yalnızca zaten süresi olan alanların süresini değiştirir. GT yeni süre mevcut süreden büyükse, LT küçükse uygular. Belgeler önemli bir ayrıntı ekler: süresi olmayan (kalıcı) bir alan, GT ve LT hesabında sonsuz süreli kabul edilir. Bu yüzden kalıcı bir alana GT ile süre veremezsiniz, çünkü hiçbir sayı sonsuzdan büyük değildir; LT ise kalıcı alana süre verir.

Koşul sağlanmadığında o alan için 0 döner ve süre değişmez. Bu davranış, "oturum süresini yalnızca uzat, asla kısaltma" gibi kuralları tek komutla uygulamanızı sağlar: aynı komutu GT ile göndermek yeterlidir.

HPEXPIRE, HEXPIREAT ve HPEXPIREAT

Süreyi milisaniye cinsinden vermek için HPEXPIRE, mutlak bir zaman damgası vermek için HEXPIREAT (saniye) ve HPEXPIREAT (milisaniye) kullanılır. Zaman damgaları Unix epoch'tan itibaren geçen saniye veya milisaniye olarak yazılır. Milisaniyelik örnekte kalan süre, komutlar arasında geçen birkaç milisaniye yüzünden 60000'in biraz altında görünür:

> DEL sensor:sensor1
(integer) 1
> HSET sensor:sensor1 air_quality 256 battery_level 89
(integer) 2
> HPEXPIRE sensor:sensor1 60000 FIELDS 1 air_quality
1) (integer) 1
> HPTTL sensor:sensor1 FIELDS 1 air_quality
1) (integer) 59994

Mutlak zaman damgası, süreyi "şu andan itibaren" değil "şu tarihte" bitirmek istediğinizde kullanışlıdır; örneğin bir kampanya alanının gece yarısı silinmesi gibi. Belgelerdeki örnekte 4102444800 yalnızca gelecekte bir zamanı temsil eden örnek bir değerdir:

> DEL sensor:sensor1
(integer) 1
> HSET sensor:sensor1 air_quality 256 battery_level 89
(integer) 2
> HEXPIREAT sensor:sensor1 4102444800 FIELDS 1 air_quality
1) (integer) 1
> HEXPIRETIME sensor:sensor1 FIELDS 1 air_quality
1) (integer) 4102444800

Kalan süreyi okumak: HTTL, HPTTL, HEXPIRETIME

HTTL kalan süreyi saniye, HPTTL milisaniye olarak verir. HEXPIRETIME ve HPEXPIRETIME ise sürenin biteceği mutlak Unix zamanını döndürür. Dört komut da her alan için ayrı değer içeren bir dizi döndürür: alan yoksa -2, alan var ama süresi yoksa -1, aksi halde süre ya da zaman damgası.

> HTTL no-key FIELDS 3 field1 field2 field3
(nil)
> HSET mykey field1 "hello" field2 "world"
(integer) 2
> HEXPIRE mykey 300 FIELDS 2 field1 field3
1) (integer) 1
2) (integer) -2
> HTTL mykey FIELDS 3 field1 field2 field3
1) (integer) 283
2) (integer) -1
3) (integer) -2

Bu örnekte field1 süreli olduğu için kalan saniyeyi, field2 süresiz olduğu için -1, hiç olmayan field3 için -2 görüyoruz. Belgelerdeki örnekte anahtar hiç yokken HTTL tek bir nil döndürüyor; istemci kodunuzda bu durumu dizi yanıtından ayrı ele almanız gerekir. Anahtar düzeyindeki TTL komutunun -1 ve -2 kodlarıyla aynı mantık izlendiği için EXPIRE ve TTL yazısındaki açıklamalar burada da geçerlidir.

Göreli süre mi mutlak zaman mı okuyacağınızı kullanım amacı belirler. Kullanıcıya "oturumunuzun bitmesine 5 dakika kaldı" demek için HTTL uygundur. Birden çok sunucunun aynı bitiş anını paylaşması ya da bitiş zamanını bir veritabanına kaydetmeniz gerekiyorsa HEXPIRETIME ya da HPEXPIRETIME daha kullanışlıdır, çünkü değer zaman geçtikçe değişmez. Belgelerdeki örnekte 300 saniyelik süre verilen iki alan için HPEXPIRETIME her iki alanda da 1715705913659 döndürür; iki alana aynı komutla süre verildiği için bitiş anları da aynıdır.

HPERSIST ile süreyi kaldırmak

HPERSIST alanı süreli (volatile) durumdan kalıcı (persistent) duruma geçirir. Dönüş kodları: süre kaldırıldıysa 1, alan var ama zaten süresi yoksa -1, alan yoksa -2.

> HSET mykey field1 "hello" field2 "world"
(integer) 2
> HEXPIRE mykey 300 FIELDS 2 field1 field2
1) (integer) 1
2) (integer) 1
> HTTL mykey FIELDS 2 field1 field2
1) (integer) 283
2) (integer) 283
> HPERSIST mykey FIELDS 1 field2
1) (integer) 1
> HTTL mykey FIELDS 2 field1 field2
1) (integer) 268
2) (integer) -1

Süre hangi durumda korunur, hangi durumda silinir?

HEXPIRE sayfası bu konuyu net bir kuralla açıklar: alan süresi yalnızca alanın içeriğini silen ya da üzerine yazan komutlarla temizlenir; bunlara HDEL ve HSET dahildir. Değeri yerine yenisini koymadan kavramsal olarak değiştiren işlemler süreye dokunmaz. Pratikte bunun anlamı şudur: süreli bir alanı HSET ile yeniden yazarsanız alan kalıcı hale gelir ve süreyi yeniden vermeniz gerekir. Bu, en sık yaşanan sürprizdir.

Süresi olan bir alana yeniden HEXPIRE çağırmak süreyi yeni değerle günceller; belgeler buna süreyi yenilemek (refresh) der. Bütün alanların süresi dolduğunda hash boşalır; belgelerdeki HPEXPIRE örneğinde iki alan 2000 milisaniye sonra silindikten sonra HGETALL mykey boş dizi döndürür.

Alan süresi başka özelliklerle de etkileşir. Keyspace bildirimlerinde HEXPIRE ve türevleri hexpired olayı üretir ve alanların süresi dolduğunda da hexpired olayı gönderilir; HPERSIST ise hpersist olayı üretir. Redis 8.8 hash alanları için alan düzeyinde bildirimler ekledi. Ayrıca Redis 8.10'daki compact hash otomatik dönüştürmesi, alan süresi kullanan hash'leri dönüştürmez. Bildirimlerin nasıl açılacağı için keyspace notifications yazısına bakın.

HSETEX: yazarken süre vermek (Redis 8.0)

HSETEX bir veya daha fazla alanı yazar ve aynı komutta süresini ayarlar. EX (saniye), PX (milisaniye), EXAT ve PXAT (mutlak zaman) ile KEEPTTL (mevcut süreyi koru) birbirini dışlar. FNX alanların hiçbiri yoksa, FXX hepsi varsa yazma yapar; bu ikisi de birbirini dışlar. Komut bütün alanlar yazıldıysa 1, hiçbiri yazılmadıysa 0 döndürür. Belgeye göre değerler üzerine yazılırken önceki süreler atılır; süreyi korumak istiyorsanız KEEPTTL vermelisiniz.

> HSETEX mykey EXAT 1740470400 FIELDS 2 field1 "Hello" field2 "World"
(integer) 1
> HTTL mykey FIELDS 2 field1 field2
1) (integer) 55627
2) (integer) 55627
> HSETEX mykey FNX EX 60 FIELDS 2 field1 "Hello" field2 "World"
(integer) 0
> HSETEX mykey FXX EX 60 KEEPTTL FIELDS 2 field1 "hello" field2 "world"
(error) ERR Only one of EX, PX, EXAT, PXAT or KEEPTTL arguments can be specified
> HSETEX mykey FXX KEEPTTL FIELDS 2 field1 "hello" field2 "world"
(integer) 1

Örnekte ikinci komut FNX kullandığı ve alanlar zaten var olduğu için hiçbir şey yazmaz. Üçüncü komut hem EX hem KEEPTTL verdiği için hata alır. Dördüncü komut değerleri günceller ama mevcut süreyi korur. HSET ardından HEXPIRE yazmak iki ayrı komut ve iki gidiş dönüştür; HSETEX bunu tek atomik adıma indirir ve iki komut arasında alanın süresiz kalması riskini ortadan kaldırır.

HGETEX ve HGETDEL: okurken süre ayarlamak ya da silmek

HGETEX istediğiniz alanların değerlerini döndürür ve isteğe bağlı olarak sürelerini ayarlar. EX, PX, EXAT, PXAT ve süreyi kaldıran PERSIST birbirini dışlar. "Her okumada oturum süresini yenile" gibi kayan süre (sliding expiration) desenleri için uygundur.

> HSET mykey field1 "Hello" field2 "World"
(integer) 2
> HGETEX mykey EX 120 FIELDS 1 field1
1) "Hello"
> HGETEX mykey EX 100 FIELDS 1 field2
1) "World"
> HTTL mykey FIELDS 2 field1 field2
1) (integer) 91
2) (integer) 85

HGETDEL ise alanları okur ve hemen siler; olmayan alanlar için nil döner. Son alan silindiğinde anahtar da silinir. Tek kullanımlık kodlar ya da bir kez işlenip atılması gereken bekleyen kayıtlar için okuma ve silmeyi tek atomik adımda yapar.

> HSET mykey field1 "Hello" field2 "World" field3 "!"
(integer) 3
> HGETDEL mykey FIELDS 2 field3 field4
1) "!"
2) (nil)
> HGETALL mykey
1) "field1"
2) "Hello"
3) "field2"
4) "World"
> HGETDEL mykey FIELDS 2 field1 field2
1) "Hello"
2) "World"
> KEYS *
(empty array)

Uygulamalı örnek: aktif oturumları saymak

Belgelerdeki "aktif oturum takibi" senaryosunu kendi komutlarımızla kuralım. Her oturum sessions:active hash'inde bir alandır, değeri kullanıcı kimliğidir ve 30 dakikalık hareketsizlik süresi vardır. Bu komutlar belgelerde çıktısıyla gösterilmediği için yanıtları aşağıda açıklıyoruz.

HSETEX sessions:active EX 1800 FIELDS 1 sess:a91f user:42
HGETEX sessions:active EX 1800 FIELDS 1 sess:a91f
HLEN sessions:active
HGETDEL sessions:active FIELDS 1 sess:a91f

İlk satır oturumu açar ve alan yazıldığı için 1 döndürür. Kullanıcı her istek yaptığında ikinci satır değeri okur ve süreyi yeniden 1800 saniyeye çeker; kullanıcı 30 dakika boyunca hiçbir istek yapmazsa alan kendiliğinden silinir. Üçüncü satır o anda süresi dolmamış oturum sayısını tamsayı olarak verir. Kullanıcı çıkış yaptığında dördüncü satır alanı okuyup siler. Bu desen Redis 8.0 gerektirir; Redis 7.4 sunucularda HSET ardından HEXPIRE göndererek aynı sonucu iki komutla elde edersiniz.

EXPIRE ile HEXPIRE karşılaştırması

Sık yapılan hatalar

• FIELDS ve alan sayısını unutmak: HEXPIRE key 60 field1 yazmak hatadır; doğrusu HEXPIRE key 60 FIELDS 1 field1.
• HSET ile süreyi silmek: Süreli alanı HSET ile yeniden yazmak süreyi temizler. Süreyi korumak için Redis 8.0 ve sonrasında HSETEX ... KEEPTTL kullanın.
• -2 kodunu hata sanmak: -2 "alan ya da anahtar yok" demektir; komut başarıyla çalışmıştır.
• GT ile kalıcı alana süre vermeye çalışmak: Kalıcı alan sonsuz kabul edildiği için koşul sağlanmaz ve 0 döner.
• Eski sunucuda yeni komut: Redis 7.4 öncesinde alan süresi yoktur, HSETEX/HGETEX/HGETDEL için en az Redis 8.0 gerekir.
• Bütün hash'e EXPIRE vermek: Yalnızca bir alanın geçici olması gerekiyorsa EXPIRE bütün nesneyi siler.

Sık Sorulan Sorular

Hash alan süresi hangi sürümle geldi?

Alan süresi komutları (HEXPIRE, HPEXPIRE, HEXPIREAT, HPEXPIREAT, HTTL, HPTTL, HEXPIRETIME, HPEXPIRETIME, HPERSIST) Redis 7.4 ile, HSETEX, HGETEX ve HGETDEL Redis 8.0 ile geldi. Sürüm yeniliklerinin tamamı için Redis 8 yenilikleri yazısına bakabilirsiniz.

Bütün alanların süresi dolarsa anahtar ne olur?

Hash boşalır; belgelerdeki örneklerde süreler dolduktan sonra HGETALL boş dizi döndürür. HGETDEL sayfası da son alan silindiğinde anahtarın silindiğini belirtir.

HINCRBY ile artırdığım sayacın süresi sıfırlanır mı?

Belgeler, süreyi yalnızca alanı silen ya da üzerine yazan komutların (HDEL, HSET gibi) temizlediğini, değeri yerine yenisini koymadan değiştiren işlemlerin süreye dokunmadığını söyler. Kendi senaryonuzu bir test sunucusunda HTTL ile doğrulamanızı öneririz.

Alan süresi dolduğunda bildirim alabilir miyim?

Evet. Keyspace bildirimleri açıksa alanların süresi dolduğunda hexpired olayı üretilir. Ayarlar için keyspace notifications yazısına bakın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Redis öğrenme rehberi · Redis hash komutları · EXPIRE ve TTL · Keyspace notifications · Redis 8 yenilikleri · Redis nedir, nasıl kullanılır