Using Field-Level Expiration in Redis Hashes – Redis Knowledge Base

Redis Cloud 7.4 adds field-level expiration for hash fields, enabling independent TTLs per field. Use it for rolling logs, granular session cleanup, and sliding-window counters without extra keys. This article covers supported commands (7.4 and 8.0), code examples, common patterns, and troubleshooting & best practices for managing hash field TTLs efficiently.

Prerequisites

Redis Cloud 7.4+ for field-level expiration; Redis Cloud 8.0+ for hash helpers (HGETEX, HSETEX, HGETDEL). See the Redis Hashes documentation.
Familiarity with hash ops (HSET, HGET, HLEN) via the hashes doc.
Client SDK with 7.4 command support (redis-py, Jedis, ioredis, etc.).
Confirm client SDK support for Redis 8.0 commands (redis-py ≥ 5.1, Jedis ≥ 5.0, ioredis ≥ 5.4).

Quick Fix Table

Problem	Likely Cause	Fast Fix
`HTTL` returns `-2`	Field missing or expired	Verify field name; recreate and set TTL.
`HTTL` returns `-1`	Field has no TTL	Apply `HEXPIRE`/`HPEXPIRE` or `HEXPIREAT`/`HPEXPIREAT`.
TTL disappears after `HSET`	Updating clears field TTL	Re-apply expiration after `HSET`; use `NX/XX` where appropriate.
Field appears to see Immediate deletion	TTL set to `0` or timestamp in past	Use a positive TTL or future timestamp.
Client says “unknown command”	SDK too old	Upgrade client; issue raw commands if supported.

What It Is

Previously, TTLs applied to the whole hash key. With field-level expiration, each field can carry its own TTL. When it expires, only that field is removed; the key remains until empty. This behavior is in Redis Cloud 7.4+. For background and performance insights, see the release notes and the engineering article Hash field expiration – Architecture and Benchmarks.

Supported Commands

Redis Cloud 7.4

Command	Purpose	Time Unit
HEXPIRE	Set TTL on fields	Seconds
HPEXPIRE	Set TTL on fields	Milliseconds
HEXPIREAT	Set expiration at timestamp	Seconds
HPEXPIREAT	Set expiration at timestamp	Milliseconds
HEXPIRETIME	Get expiration time	Seconds
HPEXPIRETIME	Get expiration time	Milliseconds
HTTL	Get remaining TTL	Seconds
HPTTL	Get remaining TTL	Milliseconds
HPERSIST	Remove field expiration	—

Note: HSET/HDEL clear TTL on affected fields; conditional options NX/XX/GT/LT supported; TTL=0 or past timestamp deletes immediately.

Please note that if the key has an expiration time this takes precedence over any hash TTL. E.g., if a hash key and various fields in the hash have a TTL, the whole key will be removed at the conclusion of its TTL even if a specific field has a longer TTL.

Redis Cloud 8.0+ (New Hash Helpers)

Command	Purpose
`HGETEX`	Atomically get a field value and set a new TTL
`HSETEX`	Atomically set a field value with TTL
`HGETDEL`	Atomically get a field value and delete it

Note: These commands simplify transactional operations that previously required multiple calls (e.g., HGET + HEXPIRE). Use them when atomicity and efficiency are important.

Code Examples

Set field TTL (seconds)

HEXPIRE myhash 60 FIELDS 2 field1 field2

Expire at specific time

HEXPIREAT myhash 1715704971 FIELDS 2 field1 field2

Inspect TTL / expire time

HTTL myhash FIELDS 2 field1 field2
HEXPIRETIME myhash FIELDS 2 field1 field2

Remove expiration

HPERSIST myhash FIELDS 1 field1

Python (redis-py)

import redis
r = redis.Redis()
r.hset('sensor:1', mapping={'air_quality': 256, 'battery_level': 89})
r.hexpire('sensor:1', 60, 'air_quality', 'battery_level')
print(r.httl('sensor:1', 'air_quality', 'battery_level'))

Common Patterns

Rolling logs / events: each event is a field with 1h TTL; HLEN for recent count.
Sliding counters: time-stamped fields (e.g., user:2025-10-07:11) expire after 48h.
Session cleanup: expire sensitive attributes without dropping the entire user hash.
Active sessions list: one hash of session fields; expirations auto-prune; HLEN is live count.

Troubleshooting & Best Practices

Scale & perf: expiration ops are O(n) by fields operated; spread bulk updates; TTL metadata overhead is small—validate with your dataset.
Correctness: rely on NX/XX to avoid unintended TTL resets; expect aggregates (e.g., HLEN) to reflect non-expired fields only.
Clients: confirm SDK support for 7.4 commands before rollout; add keyspace notifications if you need downstream reactions.
Migration Tip: When upgrading to Redis 8, you can replace paired HGET + HEXPIRE logic with HGETEX to ensure atomic reads and TTL refreshes.

Related to