|
| 1 | +--- |
| 2 | +description: "Learn how to use the HTTL command to query the remaining TTL of individual fields within a Redis hash, enabling granular cache management." |
| 3 | +--- |
| 4 | + |
| 5 | +import PageTitle from '@site/src/components/PageTitle'; |
| 6 | + |
| 7 | +# HTTL |
| 8 | + |
| 9 | +<PageTitle title="Redis HTTL Command (Documentation) | Dragonfly" /> |
| 10 | + |
| 11 | +## Syntax |
| 12 | + |
| 13 | + HTTL key FIELDS numfields field [field ...] |
| 14 | + |
| 15 | +**Time complexity:** O(N) where N is the number of fields being queried |
| 16 | + |
| 17 | +**ACL categories:** @read, @hash, @fast |
| 18 | + |
| 19 | +Returns the remaining Time-To-Live (TTL) in seconds for one or more fields of a hash stored at `key`. |
| 20 | +This allows you to inspect when individual hash fields will expire without modifying them. |
| 21 | + |
| 22 | +Unlike `TTL`, which operates at the key level, `HTTL` operates at the field level. |
| 23 | +Field-level expiry is set via [`HEXPIRE`](./hexpire.md) or [`HSETEX`](./hsetex.md). |
| 24 | + |
| 25 | +## Return |
| 26 | + |
| 27 | +[Array reply](https://valkey.io/topics/protocol/#arrays): an array of integer replies, one per field, in the same order as the fields were requested: |
| 28 | + |
| 29 | +- Integer reply: `-2` if the field does not exist in the hash, or if the hash key itself does not exist. |
| 30 | +- Integer reply: `-1` if the field exists but has no associated expiration (it persists indefinitely). |
| 31 | +- Integer reply: a positive integer representing the remaining TTL in seconds. |
| 32 | + |
| 33 | +## Examples |
| 34 | + |
| 35 | +**Fields with no expiry, one non-existent field:** |
| 36 | + |
| 37 | +```shell |
| 38 | +dragonfly> HSET myhash field1 "hello" field2 "world" |
| 39 | +(integer) 2 |
| 40 | +dragonfly> HTTL myhash FIELDS 3 field1 field2 nosuchfield |
| 41 | +1) (integer) -1 |
| 42 | +2) (integer) -1 |
| 43 | +3) (integer) -2 |
| 44 | +``` |
| 45 | + |
| 46 | +**Setting an expiry and checking the remaining TTL:** |
| 47 | + |
| 48 | +```shell |
| 49 | +dragonfly> HEXPIRE myhash 30 FIELDS 1 field1 |
| 50 | +1) (integer) 1 |
| 51 | +dragonfly> HTTL myhash FIELDS 2 field1 field2 |
| 52 | +1) (integer) 29 |
| 53 | +2) (integer) -1 |
| 54 | +``` |
| 55 | + |
| 56 | +**Key does not exist — all fields return `-2`:** |
| 57 | + |
| 58 | +```shell |
| 59 | +dragonfly> HTTL no-key FIELDS 2 field1 field2 |
| 60 | +1) (integer) -2 |
| 61 | +2) (integer) -2 |
| 62 | +``` |
| 63 | + |
| 64 | +**Wrong key type:** |
| 65 | + |
| 66 | +```shell |
| 67 | +dragonfly> SET mystring "value" |
| 68 | +"OK" |
| 69 | +dragonfly> HTTL mystring FIELDS 1 field1 |
| 70 | +(error) WRONGTYPE Operation against a key holding the wrong kind of value |
| 71 | +``` |
| 72 | + |
| 73 | +## Notes |
| 74 | + |
| 75 | +- `HTTL` is a read-only command and does not modify the hash or any field TTLs. |
| 76 | +- The reported TTL reflects the time remaining at the moment the command is executed. For precise expiry management, consider the clock resolution on the server. |
| 77 | +- To remove an expiry from a field (make it persist), re-set the field without an expiry using [`HSET`](./hset.md). |
| 78 | + |
| 79 | +## Related Commands |
| 80 | + |
| 81 | +- [`HEXPIRE`](./hexpire.md) — Set a TTL on one or more hash fields. |
| 82 | +- [`FIELDTTL`](../generic/fieldttl.md) — Retrieve the TTL of a specific field. |
| 83 | +- [`HSETEX`](./hsetex.md) — Set hash field values along with a TTL. |
| 84 | +- [`HSET`](./hset.md) — Set hash field values (no expiry). |
| 85 | +- [`HGETALL`](./hgetall.md) — Retrieve all fields and values of a hash. |
0 commit comments