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

keybodystringrequired

The key of the hash.

optionsbodyobject

Options for conditional setting and expiration.

conditionalbody'FNX' | 'fnx' | 'FXX' | 'fxx'

Conditional setting options (case-insensitive):

FNX: Only set fields if the hash does not exist
FXX: Only set fields if the hash already exists

expirationbodyobject

Expiration options for the hash.

exbodynumber

Set expiration time in seconds.

pxbodynumber

Set expiration time in milliseconds.

exatbodynumber

Set expiration as Unix timestamp in seconds.

pxatbodynumber

Set expiration as Unix timestamp in milliseconds.

keepttlbodytrue

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. Set to true to enable.

fieldsbody{ [fieldName]: TValue }required

An object of fields and their values to set.

Response

numberrequired

The number of fields that were set. Returns 0 if conditions are not met (e.g., conditional: "FNX" but hash exists, or conditional: "FXX" but hash doesn't exist).

Basic Example

// Set fields with 1 hour expirationawait redis.hsetex("user:123", { expiration: { ex: 3600 } }, {   name: "John",   email: "john@example.com" });

With FNX (only if hash doesn't exist)

// Set fields only if the hash doesn't existconst result = await redis.hsetex(  "user:456",   { conditional: "FNX" },   { name: "Jane", age: "25" });console.log(result); // 2 (if hash didn't exist)// Try again - will return 0 since hash now existsconst result2 = await redis.hsetex(  "user:456",   { conditional: "FNX" },   { email: "jane@example.com" });console.log(result2); // 0

With FXX (only if hash exists)

// First create the hashawait redis.hset("session:abc", { token: "xyz" });// Update only if hash existsconst result = await redis.hsetex(  "session:abc",   { conditional: "FXX" },   { user: "john" });console.log(result); // 1 (hash exists, field added)// Try on non-existent hashconst result2 = await redis.hsetex(  "session:nonexistent",   { conditional: "FXX" },   { user: "jane" });console.log(result2); // 0 (hash doesn't exist)

With PX (milliseconds)

// Set fields with 30 second expirationawait redis.hsetex("cache:data", { expiration: { px: 30000 } }, {   value: "cached data",  timestamp: Date.now().toString()});

With EXAT (Unix timestamp in seconds)

// Set expiration to specific timestampconst futureTime = Math.floor(Date.now() / 1000) + 7200; // 2 hours from nowawait redis.hsetex("temp:data", { expiration: { exat: futureTime } }, {   info: "temporary information" });

With PXAT (Unix timestamp in milliseconds)

// Set expiration to specific timestamp in millisecondsconst futureTime = Date.now() + 300000; // 5 minutes from nowawait redis.hsetex("session:xyz", { expiration: { pxat: futureTime } }, {   token: "abc123",  user: "john"});

Combined: Conditional + Expiration

// Set fields only if hash doesn't exist, with 1 hour expirationawait redis.hsetex(  "user:789",   {     conditional: "FNX",     expiration: { ex: 3600 }   },   {     name: "Alice",    email: "alice@example.com",    created: Date.now().toString()  });

With KEEPTTL

// First set fields with expirationawait redis.hsetex("cache:data", { expiration: { ex: 300 } }, {   value: "cached" });// Later update fields while retaining the existing TTLconst result = await redis.hsetex(  "cache:data",   { expiration: { keepttl: true } },   { updated: "yes" });console.log(result); // 1// Verify TTL is still 300 seconds (or less if time passed)const ttl = await redis.ttl("cache:data");console.log(ttl); // Should be > 0 and <= 300 (TTL was retained)

Without Options

// Just set fields without expiration or conditionsawait redis.hsetex("data:simple", undefined, {   field1: "value1",   field2: "value2" });

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