HSETEX - Upstash Documentation

The HSETEX command sets the specified fields with their values and optionally sets their expiration time or TTL. It supports conditional operations to control when fields should be set.

Arguments

keybodystrrequired

The key of the hash.

fieldbodystr

A single field name to set. Use with value parameter.

valuebodyAny

A single value to set. Use with field parameter.

valuesbodyDict[str, Any]

A dictionary of fields and their values to set. Either use field/value or values, but not both.

fnxbodybool

Only set fields if the hash does not exist.

fxxbodybool

Only set fields if the hash already exists.

exbodyint

Set expiration time in seconds.

pxbodyint

Set expiration time in milliseconds.

exatbodyint

Set expiration as Unix timestamp in seconds.

pxatbodyint

Set expiration as Unix timestamp in milliseconds.

keepttlbodybool

Retain the existing time to live (TTL) associated with the hash key when setting fields. If the hash has an expiration, it will be preserved.

Response

intrequired

0 if no fields were set, 1 if all the fields were set.

Single Field

# Set a single field with expirationresult = redis.hsetex("myhash", "field1", "Hello", ex=60)assert result == 1

Multiple Fields

# Set fields with 1 hour expirationresult = redis.hsetex(    "user:123",    values={"name": "John", "email": "john@example.com"},    ex=3600)assert result == 2

With FNX (only if hash doesn't exist)

# Set fields only if the hash doesn't existresult = redis.hsetex(    "user:456",    values={"name": "Jane", "age": "25"},    fnx=True)assert result == 2# Try again - will return 0 since hash now existsresult = redis.hsetex(    "user:456",    values={"email": "jane@example.com"},    fnx=True)assert result == 0

With FXX (only if hash exists)

# First create the hashredis.hset("session:abc", "token", "xyz")# Update only if hash existsresult = redis.hsetex(    "session:abc",    values={"user": "john"},    fxx=True)assert result == 1  # Hash exists, field added# Try on non-existent hashresult = redis.hsetex(    "session:nonexistent",    values={"user": "jane"},    fxx=True)assert result == 0  # Hash doesn't exist

With PX (milliseconds)

import time# Set fields with 30 second expirationresult = redis.hsetex(    "cache:data",    values={"value": "cached data", "timestamp": str(int(time.time()))},    px=30000)assert result == 2

With EXAT (Unix timestamp in seconds)

import time# Set expiration to specific timestampfuture_time = int(time.time()) + 7200  # 2 hours from nowresult = redis.hsetex(    "temp:data",    values={"info": "temporary information"},    exat=future_time)assert result == 1

With PXAT (Unix timestamp in milliseconds)

import time# Set expiration to specific timestamp in millisecondsfuture_time = int(time.time() * 1000) + 300000  # 5 minutes from nowresult = redis.hsetex(    "session:xyz",    values={"token": "abc123", "user": "john"},    pxat=future_time)assert result == 2

Combined: Conditional + Expiration

import time# Set fields only if hash doesn't exist, with 1 hour expirationresult = redis.hsetex(    "user:789",    values={        "name": "Alice",        "email": "alice@example.com",        "created": str(int(time.time()))    },    fnx=True,    ex=3600)assert result == 3

With KEEPTTL

# First set fields with expirationredis.hsetex("cache:data", values={"value": "cached"}, ex=300)# Later update fields while retaining the existing TTLresult = redis.hsetex("cache:data", values={"updated": "yes"}, keepttl=True)assert result == 1# Verify TTL is still 300 seconds (or less if time passed)ttl = redis.ttl("cache:data")assert ttl > 0 and ttl <= 300  # TTL was retained

Without Options

# Just set fields without expiration or conditionsresult = redis.hsetex(    "data:simple",    values={"field1": "value1", "field2": "value2"})assert result == 2

Use Cases

Session Management: Create sessions with automatic expiration
Cache with TTL: Store cached data that expires automatically
Temporary Data: Create temporary records with built-in cleanup
Rate Limiting: Store rate limit counters with automatic reset
Conditional Updates: Ensure data consistency with FNX/FXX options