Valkey Hash Field Expiration in Production: HSETEX, HGETEX, and HEXPIRE

Valkey 9.0 lets a single hash field carry its own TTL, so a session hash can drop its one-time code after five minutes while the rest of the session lives for thirty. The commands are short (HSETEX, HGETEX, HEXPIRE, and friends), but the behaviour behind them surprises teams in production. An expired field disappears from reads yet still counts in HLEN and memory until a background job reaps it. A plain HSET silently makes a volatile field permanent. Small hashes leave the compact listpack encoding the moment one field gets a TTL. And the 9.0 and 9.1 patch trains kept fixing field-expiration bugs until October 2026. This guide covers the design choice, three patterns, the memory bill, replication, and the patch you need first.

Scope and review date: November 2026. This post covers self-managed Valkey 9.0 (latest patch 9.0.7) and 9.1 (latest patch 9.1.3), with notes on the 9.2 release candidates. Commands, defaults, and version numbers were checked against the Valkey documentation, release notes, and the 9.1.3 source on 10 November 2026. They were not run in a lab, so rehearse them on staging.

Which hash field expiration commands does Valkey 9 have?

Twelve commands touch field TTLs. The since values below come from the command definitions in the Valkey 9.1.3 source and match the HSETEX, HGETEX, and HEXPIRE pages on valkey.io. The feature landed through PR #2089 in 9.0.0-rc1, and 9.0.0 went GA on 21 October 2025.

The syntax follows the Redis 8.0 API for HSETEX and HGETEX and the Redis 7.4 API for HEXPIRE, which is why Redis clients can call them. The key-level NX/XX on HSETEX is Valkey-only. For the wider product comparison, see Redis vs Valkey.

valkey-cli HSETEX session:u42 EX 1800 FIELDS 2 cart c-981 csrf 7f3a
valkey-cli HTTL session:u42 FIELDS 3 cart csrf user_id
valkey-cli HEXPIRE session:u42 600 GT FIELDS 1 cart

Interpretation: HSETEX returns 1 when every field was set and 0 when an FNX or FXX condition blocked all of them. HTTL returns one integer per field: seconds remaining, -1 for a field with no TTL, or -2 for a field that does not exist. HEXPIRE returns 1 when applied, 0 when the condition failed (here, 600 is not greater than the current TTL), 2 when the time was 0 or in the past and the field was deleted, and -2 for a missing field.

Should you use a whole-key TTL or field TTLs?

Before 9.0, different lifetimes meant one key per attribute. Field TTLs remove that, but change how eviction, encoding, and counting behave. Pick per data set.

The eviction row comes from evict.c in 9.1.3: volatile-* policies sample only the per-database expires table, which field TTLs never enter. Move sessions from key TTLs to field TTLs under volatile-lru, and they stop being eviction candidates.

valkey-cli CONFIG GET maxmemory-policy
valkey-cli CONFIG GET hash-max-listpack-*

Interpretation: if the policy starts with volatile-, either give the hash a key-level TTL as well (for example, the longest field lifetime) or accept that it is never evicted. The listpack limits tell you which hashes currently stay compact and would convert.

How do you model sessions, feature flags, and rate counters with field TTLs?

All three patterns depend on one rule from the hashes documentation: commands that overwrite a field, such as HSET and HMSET, remove its TTL. HSETEX without an expiry option behaves like HSET and also clears it. Only KEEPTTL preserves it.

Sessions with per-attribute expiry

valkey-cli HSETEX session:u42 EX 1800 FIELDS 2 user_id 42 cart c-981
valkey-cli HSETEX session:u42 PX 300000 FIELDS 1 otp 913204
valkey-cli HGETEX session:u42 EX 1800 FIELDS 2 user_id cart
valkey-cli HSETEX session:u42 FXX KEEPTTL FIELDS 1 cart c-982

Interpretation: the first two lines give the session a 30-minute life and the one-time code 5 minutes. The HGETEX line reads and slides the 30-minute window on each request. The last line updates the cart only if the field still exists (FXX) and keeps its remaining TTL. Written as plain HSET, that update would make the cart permanent.

Feature flags with expiring experiments

valkey-cli HSET flags:cust:1001 dark_mode on billing_v3 on
valkey-cli HSETEX flags:cust:1001 EX 86400 FIELDS 1 exp_checkout_v2 on
valkey-cli HGETALL flags:cust:1001

Interpretation: long-lived rollouts are plain fields; the experiment switches itself off after 24 hours, and HGETALL stops returning it as soon as the TTL passes. Check your flag service's write path: if it re-saves every flag with HSET, it removes the experiment's TTL on the first edit.

Per-user rate counters

valkey-cli <<'EOF'
MULTI
HINCRBY rl:u42 api:202611100915 1
HEXPIRE rl:u42 120 NX FIELDS 1 api:202611100915
EXEC
EOF

Interpretation: one field per user per minute window, so a user's counters share one key. HINCRBY keeps an existing field TTL (it passes the old expiry through in t_hash.c), and HEXPIRE ... NX sets the TTL only on the first hit of the window, returning 1 then 0. If you send the two commands without MULTI and a client dies between them, the next request's NX still sets the TTL. This is a fixed window. 9.0.2 fixed HINCRBY not updating volatile-key tracking (#2974), one more reason for the patch floor below.

What happens to a field after its TTL passes?

Valkey expires keys two ways: lazily, when a command touches an expired key, and actively, from a background cycle. The Valkey team's design post says field expiration deliberately has no lazy path. A read treats an expired field as nonexistent, but only the active expiry cycle deletes it.

Fields are grouped into time buckets (a "volatile set" per hash), and the cycle visits only buckets whose time has passed. In 9.1.3 it alternates between keys and fields and is capped by ACTIVE_EXPIRE_CYCLE_SLOW_TIME_PERC, 25% of CPU time at the default active-expire-effort 1 (expire.c).

valkey-cli INFO stats | grep -E '^(expired_fields|expired_keys_with_volatile_items_stale_perc|expired_time_cap_reached_count|expire_cycle_cpu_milliseconds):'
valkey-cli INFO keyspace

Interpretation: expired_fields counts reaped fields since start. expired_keys_with_volatile_items_stale_perc estimates how much of the sampled volatile data was already expired; a value that stays high means the cycle is not keeping up. A rising expired_time_cap_reached_count shows the cycle hitting its CPU budget. In the keyspace section, each dbN line ends with keys_with_volatile_items, the number of hashes holding at least one field TTL. All four fields are present from 9.0.0.

Keyspace notifications follow the same timing. The notifications page says hexpired fires when the server deletes the field, not when its TTL reaches zero, so do not drive time-critical work from it.

How much memory do volatile fields cost?

The design post measured the per-field cost on 9.0: an 8-byte expiry timestamp plus tracking in the volatile set, "between 16 and 29 bytes per field" in total depending on how many fields have TTLs and how spread out the times are. The higher end hits small hashes, because on 9.0 and 9.1 a hash with any volatile field cannot stay in listpack encoding. The 9.1.3 source converts a listpack hash to a hashtable as soon as a field gets an expiry. PR #3212 keeps small volatile hashes in listpack, but it shipped only in 9.2.0-rc1.

valkey-cli HSET demo:h a 1 b 2
valkey-cli OBJECT ENCODING demo:h
valkey-cli MEMORY USAGE demo:h
valkey-cli HEXPIRE demo:h 600 FIELDS 1 a
valkey-cli OBJECT ENCODING demo:h
valkey-cli MEMORY USAGE demo:h

Interpretation: on 9.0 or 9.1, expect listpack before the HEXPIRE and hashtable after it, with a jump in MEMORY USAGE. Multiply that jump by your count of small hashes, and measure on staging.

For steady state, the design post gives a sizing rule: memory equals insert rate times average TTL times average item size. Its own test inserted 300,000 fields per second with a 10-second TTL and about 80 bytes per item (61 base plus 19 for expiry), and predicted about 230 MB, which matched what it observed.

# fields/s x TTL seconds x bytes per field
echo $(( 300000 * 10 * 80 ))   # 240000000 bytes, about 229 MiB

Interpretation: plug in your own write rate, TTL, and per-field size. The rule holds only while active expiry keeps up. Note that MEMORY USAGE on 9.0 and 9.1 does not count expired-but-unreaped fields; 9.2.0-rc2 fixes that (#5092).

How do field TTLs replicate and persist?

The primary owns expiry. In 9.1.3, t_hash.c rewrites relative times before they reach replicas and the AOF, so a replica or a reload sees the same absolute deadline:

• HSETEX ... EX or PX is propagated as HSETEX ... PXAT with a millisecond timestamp.
• HEXPIRE, HPEXPIRE, and HEXPIREAT are propagated as HPEXPIREAT.
• HGETEX is never propagated as itself, only as HPEXPIREAT, HPERSIST, or HDEL.
• Each field the active cycle reaps is propagated as HDEL, followed by DEL when the hash empties.

Replicas do not reap fields themselves. They hide expired fields on read, judged by their own clock, and wait for the primary's HDEL. So a replica's HLEN can briefly exceed the primary's, and clock skew between nodes shifts the moment a field disappears from replica reads. RDB files store a hash with field TTLs as the RDB_TYPE_HASH_2 type, which needs RDB version 80.

for h in valkey-primary valkey-replica-1; do
  printf '%s ' "$h"
  valkey-cli -h "$h" HTTL session:u42 FIELDS 2 cart otp | tr '\n' ' '
  echo
done

Interpretation: both nodes should agree within a second or two. A field that reads -2 on the primary but keeps a TTL on the replica matches the divergence fixed in PR #4772: before 9.0.7 and 9.1.3, HDEL, HGETDEL, HPERSIST, and HEXPIRE propagated fields the primary already treated as expired. An AOF reload diverged the same way.

Which Valkey patch do you need before adopting field TTLs?

These are the field-expiration fixes in the 9.0 and 9.1 release notes:

The floor is 9.0.7 or 9.1.3, released on 27 and 26 October 2026. Those releases also carry a cluster Pub/Sub security fix, covered with the rest of the version policy in our Valkey patch floor guide. Check every node, because the redis_version field in INFO does not report the Valkey release.

valkey-cli INFO server | grep -E '^(valkey_version|redis_version):'

Interpretation: read valkey_version; redis_version is a fixed compatibility value. Every primary and replica must be at the floor.

Who can run HGETEX?

HGETEX reads values, but it is a write command: an EX changes TTLs, and a past EXAT deletes fields. Before PR #4576, its key specification asked only for read access, so a user granted %R~ on a key pattern could change TTLs or delete fields it was only allowed to read.

valkey-cli ACL DRYRUN reporting HGETEX session:u42 EX 60 FIELDS 1 cart
valkey-cli ACL DRYRUN reporting HGET session:u42 cart

Interpretation: on 9.0.6, 9.1.2, or later, a user whose key permission is only %R~session:* gets OK for HGET and a permission error naming the key for HGETEX. If HGETEX returns OK for a read-only user, the node is below the fix. Read paths that need values should use HGET or HMGET.

What do field TTLs do to an upgrade rollback?

Upgrading to 9.x does not, by itself, stop you going back. Writing the first field TTL does. Valkey 7.2 and 8.0 cannot load a 9.x RDB file, and 8.1 can try only with rdb-version-check relaxed, which stops at a hash with field TTLs. A 9.1 or later primary can send an older replica a full sync in RDB 11 (PR #2735), but per the PR, "if any new features that the replica can't handle (such as hash-field expiration and atomic slot migration) are in use, the full sync is aborted". The details are in our Valkey RDB compatibility and rollback guide.

valkey-cli INFO keyspace | grep -o 'keys_with_volatile_items=[0-9]*'

Interpretation: any value above 0 means a full sync to a 7.2 or 8.x replica will fail and a downgrade needs a logical copy instead of an RDB file. Keep this check in your rollback runbook.

Which client libraries support the field TTL commands?

Because the syntax matches Redis, most Redis clients can send the 9.0 commands; the 9.1 additions are patchier. From changelogs and source read on 10 November 2026:

With valkey-py 6.2.0, send HTTL, HEXPIRE, and HGETEX through execute_command, which returns the raw reply list. Whatever the client, test the exact calls against a 9.1.3 staging node.

Frequently asked questions

Key takeaways

Review your Valkey field TTL design with JusDB

Field TTLs touch data modelling, memory sizing, eviction, ACLs, and your upgrade plan at once, and the first one written fixes your rollback point.

JusDB's Valkey consulting team can review your hash design and client code, size memory for volatile fields, check your patch level and ACLs, and plan the rollout and rollback points.

Related reading

• Redis Memory Optimization: Encoding, TTLs, and Eviction Policies
• Valkey 9.1 for Operators: What Changed and How to Upgrade
• Valkey Performance Tuning: Memory, Persistence, and Cluster Config
• Valkey documentation: Hashes and field expiration