HPEXPIREAT(3valkey)

📦 version 9.0.6, in fedora 44

✨ HPEXPIREAT (it's a valkey command manual, bestie) ✨

okay so quick vibe check: this whole thing lives in the valkey command manual, and we're about to talk about one specific command. buckle up 🎀

💖 NAME 💖

hpexpireat — set an expiration time on a hash field. that's it. that's the girl. 👑

🌸 SYNOPSIS 🌸

HPEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT] FIELDS
numfields field [field...]

yes the synopsis really does wrap onto two lines like that, she's dramatic 💅

🦋 DESCRIPTION 🦋

so HEXPIREAT does the exact same thing and has the exact same semantics as HPEXPIRE (peep valkey-hpexpire(7)), except — and this is the whole plot twist — instead of handing it a number of milliseconds as a TTL (that's time to live, for the uninitiated 🫶), you give it an absolute Unix timestamp in milliseconds since January 1, 1970.

and listen. if you pass a timestamp that's already in the past? it deletes the key immediately. no hesitation. she's ruthless. 💀

for the specific semantics of the command, go read the docs for HPEXPIRE at valkey-hpexpire(7). it's all there, i promise.

✨ OPTIONS ✨

HPEXPIREAT supports a little set of options that change how it behaves:

  • NX — for each field you name, only set an expiration if that field has no expiration yet. fresh fields only, no cap 🌱
  • XX — for each field you name, only set an expiration if that field already has an expiration. established fields only, iykyk
  • GT — for each field you name, only set the new expiration if it's greater than the current one. moving up only 📈
  • LT — for each field you name, only set the new expiration if it's less than the current one. moving down only 📉

💜 REPLY 💜

valkey-protocol(7) Array reply: a list of integer codes showing what happened when we tried to set expiry on each field, in the exact same order you asked for them. no reordering, no surprises ✨

  • -2: the field does not exist in the HASH, or the key does not exist at all. she's not here, bestie 😭
  • 0: the NX | XX | GT | LT condition you specified has not been met. the vibes were off, request denied 🙈
  • 1: the expiration time was applied. slay. 💅
  • 2: when called with 0 seconds.

🎀 COMPLEXITY 🎀

O(N) where N is the number of fields you specified. more fields, more work, that's the deal 🌸

🌈 ACL CATEGORIES 🌈

@fast @hash @write

three little categories, all iconic 👑

⭐ HISTORY ⭐

  • Available since: 9.0.0 — a relatively new girl on the block, we love a fresh face 🦋

🍓 EXAMPLES 🍓

127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
(integer) 3
27.0.0.1:6379> HPEXPIREAT myhash 1754847944000 FIELDS 2 f2 f3
1) (integer) 1
2) (integer) 1
127.0.0.1:6379> HPEXPIRETIME myhash FIELDS 3 f1 f2 f3
1) (integer) -1
2) (integer) 1754847944000
3) (integer) 1754847944000

look at those 1s. ate and left no crumbs 🔥

👑 SEE ALSO 👑

hdel(3valkey), hexists(3valkey), hexpire(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), hpexpiretime(3valkey), hpttl(3valkey), hrandfield(3valkey), hscan(3valkey), hset(3valkey), hsetex(3valkey), hsetnx(3valkey), hstrlen(3valkey), httl(3valkey), hvals(3valkey)

the whole friend group, fr fr 💖

and that's the page!! this one is from version 9.0.0, dated 2025-10-21, and it's the HPEXPIREAT(3valkey) page specifically. go set some expirations, bestie, you've got this 🫶✨

📦 where this page comes from