HSETEX(3valkey)

✨ HSETEX ✨

okay bestie, so this is HSETEX from the Valkey Command Manual (that's hsetex(3valkey), for the record) and it is genuinely one of my faves 💖

---

🌸 NAME 🌸

hsetex — set the value of one or more fields of a given hash key, and optionally set their expiration time. it's giving "HSET but with a glow-up" 💅

---

🦋 SYNOPSIS 🦋

HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT
unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS
numfields field value [field value ...]

---

💜 DESCRIPTION 💜

so HSETEX lets you set the value of one or more fields on a given hash key, and optionally mess with their expiration time. that's the whole vibe ✨

here's the tea on what it returns: it gives back 1 if all the provided fields got set, or 0 if FNX or FXX was provided and none of the specified fields were set.

and like, if you don't pass any optional flags at all? it behaves exactly like a normal valkey-hset(7) HSET command. literally identical, no cap 🫶

---

🎀 OPTIONS 🎀

HSETEX supports a lil set of options that change up its behavior:

• FNX — only set the fields if none of them already exist 👀
• FXX — only set the fields if all of them already exist 👑
• EX seconds — set the specified expiration time in seconds ⏱️
• PX milliseconds — set the specified expiration time in milliseconds ⏱️
• EXAT unix-time-seconds — set the specified Unix time in seconds for when the fields will expire 📅
• PXAT unix-time-milliseconds — set the specified Unix time in milliseconds at which the fields will expire 📅
• KEEPTTL — retain the TTL associated with the fields 🫧

note for the following, bestie, pls read this part, it matters:

1. The EX, PX, EXAT, PXAT, and KEEPTTL options are mutually exclusive — pick ONE, not all of them, okay? 😭
2. Setting a value on a volatile hash field (a field which has an assigned expiration time) will remove the expiration for that field.
3. Providing 0 expiration TTL via EX or PX optional arguments will result in the specified fields immediately expiring and being removed from the hash. gone. poof. 💀
4. Providing a past expiration time via EXAT or PXAT optional arguments will result in the specified fields immediately expiring and being removed from the hash. same energy 💀

---

🌈 REPLY 🌈

RESP2

one of the following, bestie:

• valkey-protocol(7) Integer reply: 0 if none of the provided fields' values and/or expiration times were set.
• valkey-protocol(7) Integer reply: 1 if all the fields' values and/or expiration times were set.

RESP3

one of the following:

• valkey-protocol(7) Integer reply: 0 if none of the provided fields value and or expiration time was set.
• valkey-protocol(7) Integer reply: 1 if all the fields value and or expiration time was set.

---

⚡ COMPLEXITY ⚡

O(N) where N is the number of specified fields. linear, we love a predictable queen 👑

---

🧚 ACL CATEGORIES 🧚

@fast @hash @write

---

📜 HISTORY 📜

• Available since: 9.0.0 🎂

---

🍓 EXAMPLES 🍓

add 3 new items without expiration time to a myhash:

127.0.0.1:6379> HSETEX myhash FIELDS 3 f1 v1 f2 v2 f3 v3
(integer) 1

unsuccessful attempt setting expiration time on EXISTING fields (it said no 🙈):

127.0.0.1:6379> HSETEX myhash FNX EX 10 FIELDS 2 f2 v2 f3 v3
(integer) 0

successful attempt setting expiration time on EXISTING fields (slay 🔥):

127.0.0.1:6379> HSETEX myhash FXX EX 10 FIELDS 2 f2 v2 f3 v3
(integer) 1

verify hash fields expiration time:

127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
1) (integer) -1
2) (integer) 8
3) (integer) 8

override all hash items — this will also persist the fields:

127.0.0.1:6379> HSETEX myhash FIELDS 3 f1 v1 f2 v2 f3 v3
(integer) 1
127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
1) (integer) -1
2) (integer) -1
3) (integer) -1

setting expiration time in the past will remove all the elements in the hash:

127.0.0.1:6379> HSETEX EX 0 myhash FIELDS 3 f1 v1 f2 v2 f3 v3
(integer) 1
127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
1) (integer) -2
2) (integer) -2
3) (integer) -2
127.0.0.1:6379> HLEN myhash
(integer) 0
127.0.0.1:6379> EXISTS myhash
(integer) 0

---

👑 SEE ALSO 👑

the whole friend group, fr fr:

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

---

and that's the whole page bestie, hope it ate 💅 this one's version 9.0.0, dated 2025-10-21 — go forth and expire some fields (responsibly) 🦋✨