From a4a8e54dd8a44e1f5b52d4b869a09d0c8278ef2a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Mar 2026 14:01:32 +0000 Subject: [PATCH 1/6] Initial plan From 518e95efbbb1a5ed8df5a6b7fabbeae5d7ca5541 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Mar 2026 14:07:36 +0000 Subject: [PATCH 2/6] Add HTTL command documentation page Co-authored-by: romange <3674760+romange@users.noreply.github.com> --- docs/command-reference/hashes/httl.md | 99 +++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/command-reference/hashes/httl.md diff --git a/docs/command-reference/hashes/httl.md b/docs/command-reference/hashes/httl.md new file mode 100644 index 00000000..23cae40a --- /dev/null +++ b/docs/command-reference/hashes/httl.md @@ -0,0 +1,99 @@ +--- +description: "Learn how to use the HTTL command to query the remaining TTL of individual fields within a Redis hash, enabling granular cache management." +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# HTTL + + + +## Syntax + + HTTL key FIELDS numfields field [field ...] + +**Time complexity:** O(N) where N is the number of fields being queried + +**ACL categories:** @read, @hash, @fast + +Returns the remaining Time-To-Live (TTL) in seconds for one or more fields of a hash stored at `key`. +This allows you to inspect when individual hash fields will expire without modifying them. + +Unlike `TTL`, which operates at the key level, `HTTL` operates at the field level. +Field-level expiry is set via [`HEXPIRE`](./hexpire.md) or [`HSETEX`](./hsetex.md). + +## Return + +[Array reply](https://valkey.io/docs/latest/develop/reference/protocol-spec/#arrays): an array of integer replies, one per field, in the same order as the fields were requested: + +- Integer reply: `-2` if the field does not exist in the hash, or if the hash key itself does not exist. +- Integer reply: `-1` if the field exists but has no associated expiration (it persists indefinitely). +- Integer reply: a positive integer representing the remaining TTL in seconds. + +[Simple error reply](https://valkey.io/docs/latest/develop/reference/protocol-spec/#simple-errors): + +- If the `FIELDS` argument is missing or not at the correct position, a syntax error is returned. +- If `numfields` does not match the number of field arguments provided, a syntax error is returned. +- If the key exists but is not a hash, a `WRONGTYPE` error is returned. + +## Parameters + +| Parameter | Description | +|-------------|-------------------------------------------------------------| +| `key` | The hash key to inspect. | +| `numfields` | The number of field names that follow. | +| `field` | One or more field names whose remaining TTL you want to query. | + +## Examples + +**Fields with no expiry, one non-existent field:** + +```shell +dragonfly> HSET myhash field1 "hello" field2 "world" +(integer) 2 +dragonfly> HTTL myhash FIELDS 3 field1 field2 nosuchfield +1) (integer) -1 +2) (integer) -1 +3) (integer) -2 +``` + +**Setting an expiry and checking the remaining TTL:** + +```shell +dragonfly> HEXPIRE myhash 30 FIELDS 1 field1 +1) (integer) 1 +dragonfly> HTTL myhash FIELDS 2 field1 field2 +1) (integer) 29 +2) (integer) -1 +``` + +**Key does not exist — all fields return `-2`:** + +```shell +dragonfly> HTTL no-key FIELDS 2 field1 field2 +1) (integer) -2 +2) (integer) -2 +``` + +**Wrong key type:** + +```shell +dragonfly> SET mystring "value" +"OK" +dragonfly> HTTL mystring FIELDS 1 field1 +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +## Notes + +- `HTTL` is a read-only command and does not modify the hash or any field TTLs. +- 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. +- To remove an expiry from a field (make it persist), re-set the field without an expiry using [`HSET`](./hset.md). +- For millisecond precision, use the `HPTTL` command when it becomes available. + +## Related Commands + +- [`HEXPIRE`](./hexpire.md) — Set a TTL on one or more hash fields. +- [`HSETEX`](./hsetex.md) — Set hash field values along with a TTL. +- [`HSET`](./hset.md) — Set hash field values (no expiry). +- [`HGETALL`](./hgetall.md) — Retrieve all fields and values of a hash. From 1d4c10b41c4180c255162970676078193d8dba2d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Mar 2026 17:24:53 +0000 Subject: [PATCH 3/6] Remove Simple error reply section and Parameters table from HTTL docs Co-authored-by: romange <3674760+romange@users.noreply.github.com> --- docs/command-reference/hashes/httl.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/command-reference/hashes/httl.md b/docs/command-reference/hashes/httl.md index 23cae40a..0c2d5db6 100644 --- a/docs/command-reference/hashes/httl.md +++ b/docs/command-reference/hashes/httl.md @@ -30,20 +30,6 @@ Field-level expiry is set via [`HEXPIRE`](./hexpire.md) or [`HSETEX`](./hsetex.m - Integer reply: `-1` if the field exists but has no associated expiration (it persists indefinitely). - Integer reply: a positive integer representing the remaining TTL in seconds. -[Simple error reply](https://valkey.io/docs/latest/develop/reference/protocol-spec/#simple-errors): - -- If the `FIELDS` argument is missing or not at the correct position, a syntax error is returned. -- If `numfields` does not match the number of field arguments provided, a syntax error is returned. -- If the key exists but is not a hash, a `WRONGTYPE` error is returned. - -## Parameters - -| Parameter | Description | -|-------------|-------------------------------------------------------------| -| `key` | The hash key to inspect. | -| `numfields` | The number of field names that follow. | -| `field` | One or more field names whose remaining TTL you want to query. | - ## Examples **Fields with no expiry, one non-existent field:** From 25b6c21fe93d96ec78173c7780207ceef908ac59 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Mar 2026 17:28:08 +0000 Subject: [PATCH 4/6] Update HTTL docs: remove HPTTL note, add FIELDTTL to related commands Co-authored-by: romange <3674760+romange@users.noreply.github.com> --- docs/command-reference/hashes/httl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/command-reference/hashes/httl.md b/docs/command-reference/hashes/httl.md index 0c2d5db6..e026abab 100644 --- a/docs/command-reference/hashes/httl.md +++ b/docs/command-reference/hashes/httl.md @@ -75,11 +75,11 @@ dragonfly> HTTL mystring FIELDS 1 field1 - `HTTL` is a read-only command and does not modify the hash or any field TTLs. - 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. - To remove an expiry from a field (make it persist), re-set the field without an expiry using [`HSET`](./hset.md). -- For millisecond precision, use the `HPTTL` command when it becomes available. ## Related Commands - [`HEXPIRE`](./hexpire.md) — Set a TTL on one or more hash fields. +- `FIELDTTL` — Retrieve the TTL of a specific field. - [`HSETEX`](./hsetex.md) — Set hash field values along with a TTL. - [`HSET`](./hset.md) — Set hash field values (no expiry). - [`HGETALL`](./hgetall.md) — Retrieve all fields and values of a hash. From 37a05831591c150903cd02c2d6b49402db05eb4b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Mar 2026 18:04:56 +0000 Subject: [PATCH 5/6] Fix FIELDTTL link to point to generic/fieldttl.md Co-authored-by: romange <3674760+romange@users.noreply.github.com> --- docs/command-reference/hashes/httl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/command-reference/hashes/httl.md b/docs/command-reference/hashes/httl.md index e026abab..c303623f 100644 --- a/docs/command-reference/hashes/httl.md +++ b/docs/command-reference/hashes/httl.md @@ -79,7 +79,7 @@ dragonfly> HTTL mystring FIELDS 1 field1 ## Related Commands - [`HEXPIRE`](./hexpire.md) — Set a TTL on one or more hash fields. -- `FIELDTTL` — Retrieve the TTL of a specific field. +- [`FIELDTTL`](../generic/fieldttl.md) — Retrieve the TTL of a specific field. - [`HSETEX`](./hsetex.md) — Set hash field values along with a TTL. - [`HSET`](./hset.md) — Set hash field values (no expiry). - [`HGETALL`](./hgetall.md) — Retrieve all fields and values of a hash. From 8c8484fe9ddd741a9638c34a826be0cc2894c1e2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Mar 2026 22:03:44 +0000 Subject: [PATCH 6/6] Fix Array reply link to use valkey.io/topics/protocol/#arrays Co-authored-by: romange <3674760+romange@users.noreply.github.com> --- docs/command-reference/hashes/httl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/command-reference/hashes/httl.md b/docs/command-reference/hashes/httl.md index c303623f..c4592a8f 100644 --- a/docs/command-reference/hashes/httl.md +++ b/docs/command-reference/hashes/httl.md @@ -24,7 +24,7 @@ Field-level expiry is set via [`HEXPIRE`](./hexpire.md) or [`HSETEX`](./hsetex.m ## Return -[Array reply](https://valkey.io/docs/latest/develop/reference/protocol-spec/#arrays): an array of integer replies, one per field, in the same order as the fields were requested: +[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: - Integer reply: `-2` if the field does not exist in the hash, or if the hash key itself does not exist. - Integer reply: `-1` if the field exists but has no associated expiration (it persists indefinitely).