HEXPIRE(3valkey)

💖 HEXPIRE 💖

okay bestie, so this is the manual page for hexpire from the Valkey Command Manual, section 3valkey. yes it's a hash-field-expiry situation and yes it's iconic. let's get into it 🫶

---

✨ NAME ✨

hexpire — set expiry time on hash fields. that's it, that's the whole thing. a little countdown timer but for one specific field inside your hash. slay 💅

---

🌸 SYNOPSIS 🌸

HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field
[field...]

---

🦋 DESCRIPTION 🦋

okay so the HEXPIRE command lets you mess with the expiration time of hash fields that already exist. when you set an expiration time on a hash field, that's literally the thing that decides when the field gets automatically deleted. bye bestie 👋

not me needing to say this but: if you pass a millisecond time of 0, the field expires immediately and gets deleted. like instantly. gone. no take-backs. 😭

---

🎀 OPTIONS 🎀

the HEXPIRE command supports a lil set of options that change up its behavior:

• NX — for each field you specify, it only sets the expiration when that field has no expiration at all. brand new timer energy ✨
• XX — for each field you specify, it only sets the expiration when that field already has an expiration. gotta have one to get one, iykyk.
• GT — for each field you specify, it only sets the expiration when the new expiration is greater than the current one. only bigger, only better 📈
• LT — for each field you specify, it only sets the expiration when the new expiration is less than the current one. only smaller, only sooner 📉

---

💜 REPLY 💜

valkey-protocol(7) Array reply: a list of integer codes telling you how setting the expiry went for each field you asked about, in the exact same order you requested them. like a little report card, one line per field 📝

• -2: the field does not exist in the HASH, or the key does not exist. it's giving "who? never met her" 💀
• 0: the NX | XX | GT | LT condition you specified has not been met. vibe check failed, sorry babe.
• 1: the expiration time was applied. ate. 🔥
• 2: when called with 0 seconds. instant-delete behavior, special little code for a special little situation 👑

---

⭐ COMPLEXITY ⭐

O(N) where N is the number of fields you specified. so like, more fields = more work, obviously, it's giving linear. 🧚

---

🌈 ACL CATEGORIES 🌈

@fast @hash @write

---

👑 HISTORY 👑

• Available since: 9.0.0 — a modern queen, born in the 9 era ✨

---

🔥 EXAMPLES 🔥

127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
(integer) 3
27.0.0.1:6379> HEXPIRE myhash 10 FIELDS 2 f2 f3
1) (integer) 1
2) (integer) 1
127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
1) (integer) -1
2) (integer) 8
3) (integer) 8

so we made three fields, slapped a 10 second expiry on f2 and f3 (both said 1, we love that for them 💖), and then HTTL was like "f1? never had a timer, -1" and "f2 and f3? 8 seconds left bestie" 🕐✨ periodt.

---

🫶 SEE ALSO 🫶

hdel(3valkey), hexists(3valkey), hexpireat(3valkey), hexpiretime(3valkey), hget(3valkey), hgetall(3valkey), hgetex(3valkey), hincrby(3valkey), hincrbyfloat(3valkey), hkeys(3valkey), hlen(3valkey), hmget(3valkey), hmset(3valkey), hpersist(3valkey), hpexpire(3valkey), hpexpireat(3valkey), hpexpiretime(3valkey), hpttl(3valkey), hrandfield(3valkey), hscan(3valkey), hset(3valkey), hsetex(3valkey), hsetnx(3valkey), hstrlen(3valkey), httl(3valkey), hvals(3valkey) — the whole hash friend group, go say hi 💅

---

and that's the page!! this was Valkey 9.0.0, dated 2025-10-21, from the HEXPIRE(3valkey) page. mwah, go expire some fields responsibly bestie 🎀💖✨