HTTL(3valkey)

📦 version 9.0.6, in fedora 44

💖 HTTL — the "how long do my hash fields have left" tea 💖

okay bestie, imagine you're the manual page for httl from the valkey command manual. that's me. hi. i'm the one that tells you how many seconds a hash field has left to live before it expires and gets yeeted. 🫶

✨ NAME ✨

httl — returns the remaining time to live (in seconds) of a hash key's field(s) that have an associated expiration.

like. the countdown. in seconds. for hash fields specifically. 💅

🌸 SYNOPSIS 🌸

HTTL key FIELDS numfields field [field...]

🦋 DESCRIPTION 🦋

so the HTTL command gives you back the remaining time to live of hash field(s) that have an expiration time attached to them. it's the introspective bestie move: a Valkey client can use it to check how many seconds a given hash field is gonna stay part of the hash object before it dips. 😭

also, go look at the valkey-hpttl(7) HPTTL command — it's the exact same info but with millisecond resolution, for when you're feeling extra precise. ✨

🔥 REPLY 🔥

valkey-protocol(7) Array reply: a list of values tied to the result of getting the remaining time-to-live of the specific fields, in the same order as they were requested. no shuffling. order is preserved. periodt. 👑

  • -2: the field does not exist in the provided hash key, or the hash key is empty.
  • -1: the field does exist in the provided hash key, but it has no expiration associated with it. immortal field energy fr fr.
  • valkey-protocol(7) Integer: the expiration time associated with the hash key field, in seconds.

💫 COMPLEXITY 💫

O(N) where N is the number of specified fields.

👑 ACL CATEGORIES 👑

@fast @hash @read

🎀 HISTORY 🎀

  • Available since: 9.0.0 — a fresh baby, a new icon, we love to see it. 🍼✨

🌈 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 4 f1 f2 f3 non-exist
1) (integer) -1
2) (integer) 8
3) (integer) 8
4) (integer) -2

look at that last one: f1 says -1 (no expiry, living forever, main character), f2 and f3 say 8 (ticking down, we're stressed), and non-exist says -2 (doesn't even go here 💀).

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

the whole hash fam, all together, one big group chat. 🫶

okay that's the whole page, mwah 💋 — this was 9.0.0, dated 2025-10-21, straight from the valkey command manual. go check on your expiring fields bestie, they're lowkey counting down as we speak 🕰️✨

📦 where this page comes from