Skip to main content
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

​
key
str
required
The key of the hash.
​
field
str
A single field name to set. Use with value parameter.
​
value
Any
A single value to set. Use with field parameter.
​
values
Dict[str, Any]
A dictionary of fields and their values to set. Either use field/value or values, but not both.
​
fnx
bool
Only set fields if the hash does not exist.
​
fxx
bool
Only set fields if the hash already exists.
​
ex
int
Set expiration time in seconds.
​
px
int
Set expiration time in milliseconds.
​
exat
int
Set expiration as Unix timestamp in seconds.
​
pxat
int
Set expiration as Unix timestamp in milliseconds.
​
keepttl
bool
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

0 if no fields were set, 1 if all the fields were set.
# Set a single field with expiration
result = redis.hsetex("myhash", "field1", "Hello", ex=60)
assert result == 1

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

# Set fields only if the hash doesn't exist
result = redis.hsetex(
    "user:456",
    values={"name": "Jane", "age": "25"},
    fnx=True
)
assert result == 2

# Try again - will return 0 since hash now exists
result = redis.hsetex(
    "user:456",
    values={"email": "jane@example.com"},
    fnx=True
)
assert result == 0

# First create the hash
redis.hset("session:abc", "token", "xyz")

# Update only if hash exists
result = redis.hsetex(
    "session:abc",
    values={"user": "john"},
    fxx=True
)
assert result == 1  # Hash exists, field added

# Try on non-existent hash
result = redis.hsetex(
    "session:nonexistent",
    values={"user": "jane"},
    fxx=True
)
assert result == 0  # Hash doesn't exist

import time

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

import time

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

import time

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

import time

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

# First set fields with expiration
redis.hsetex("cache:data", values={"value": "cached"}, ex=300)

# Later update fields while retaining the existing TTL
result = 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

# Just set fields without expiration or conditions
result = 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