Skip to content

Commit 0ce4e3e

Browse files
Copilotromange
andauthored
docs: Add HTTL command reference page (#513)
* Initial plan * Add HTTL command documentation page Co-authored-by: romange <3674760+romange@users.noreply.github.com> * Remove Simple error reply section and Parameters table from HTTL docs Co-authored-by: romange <3674760+romange@users.noreply.github.com> * Update HTTL docs: remove HPTTL note, add FIELDTTL to related commands Co-authored-by: romange <3674760+romange@users.noreply.github.com> * Fix FIELDTTL link to point to generic/fieldttl.md Co-authored-by: romange <3674760+romange@users.noreply.github.com> * Fix Array reply link to use valkey.io/topics/protocol/#arrays Co-authored-by: romange <3674760+romange@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: romange <3674760+romange@users.noreply.github.com>
1 parent ca7fffa commit 0ce4e3e

1 file changed

Lines changed: 85 additions & 0 deletions

File tree

  • docs/command-reference/hashes
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
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

Comments
 (0)