Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

HEXPIRE

Last updated 
HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]
Group
Hash
Complexity
O(N) where N is the number of fields given
Arity
-6 (at least 6 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

HEXPIRE gives each listed field of the hash at key a time to live of seconds. When the time passes, the field is removed; when the last field of a hash is removed this way, the key is deleted too. The key itself keeps its own time to live, if any.

A seconds value of 0 removes the fields at once (result code 2).

FIELDS numfields must be followed by exactly numfields field names. The condition flag and the FIELDS block can come in either order after seconds.

Options

Section titled “Options”
Option Effect
NX Set the TTL only on fields that have none.
XX Set the TTL only on fields that already have one.
GT Set the TTL only if it is later than the field’s current one. A field without a TTL never matches.
LT Set the TTL only if it is earlier than the field’s current one. A field without a TTL always matches.

Only one condition can be given (repeating the same one is allowed).

Return value

Section titled “Return value”

An array with one integer per field, in the order given. The reply is the same under RESP2 and RESP3.

Code Meaning
-2 The field does not exist, or the key does not exist.
0 The condition (NX, XX, GT, LT) was not met; nothing changed.
1 The time to live was set.
2 The time was 0 or already in the past, so the field was deleted.

Errors:

  • WRONGTYPE if key holds a value that is not a hash (checked first).
  • ERR value is not an integer or out of range if seconds is not an integer, and ERR invalid expire time, must be >= 0 if it is negative.
  • ERR Parameter `numFields` should be greater than 0 if numfields is not a positive integer.
  • ERR wrong number of arguments if fewer field names follow than numfields says.
  • ERR Multiple condition flags specified for two different conditions.
  • ERR FIELDS keyword specified multiple times, ERR missing FIELDS argument, or ERR unknown argument: <arg> (including extra names after the field list).
  • ERR invalid expire time in 'hexpire' command if the resulting time is too far in the future.

Examples

Section titled “Examples”
127.0.0.1:6379> HSET session:9 token "abc" user "42"
(integer) 2
127.0.0.1:6379> HEXPIRE session:9 60 FIELDS 2 token missing
1) (integer) 1
2) (integer) -2
127.0.0.1:6379> HEXPIRE session:9 30 GT FIELDS 1 token
1) (integer) 0
127.0.0.1:6379> HTTL session:9 FIELDS 2 token user
1) (integer) 60
2) (integer) -1
127.0.0.1:6379> HEXPIRE session:9 0 FIELDS 1 token
1) (integer) 2
127.0.0.1:6379> HKEYS session:9
1) "user"

Compatibility

Section titled “Compatibility”

Same arguments and per-field result codes as Redis 7.4. Valkey 8 does not have hash field expiration.

See also

Section titled “See also”

HPEXPIRE, HEXPIREAT, HTTL, HPERSIST, HSETEX, HGETEX, EXPIRE