# HEXPIRE

> Set a time to live in seconds on one or more hash fields.

URL: https://docs.hotkv.com/commands/hexpire/

```
HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]
```

- Group: Hash
- Complexity: O(N) where N is the number of fields given
- 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

| 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

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

```
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

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

## See also

[HPEXPIRE](https://docs.hotkv.com/commands/hpexpire/index.md), [HEXPIREAT](https://docs.hotkv.com/commands/hexpireat/index.md), [HTTL](https://docs.hotkv.com/commands/httl/index.md),
[HPERSIST](https://docs.hotkv.com/commands/hpersist/index.md), [HSETEX](https://docs.hotkv.com/commands/hsetex/index.md), [HGETEX](https://docs.hotkv.com/commands/hgetex/index.md),
[EXPIRE](https://docs.hotkv.com/commands/expire/index.md)