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#

keystringrequired#

The key of the hash.

optionsobject#

Options for conditional setting and expiration.

Show properties

conditional'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

expirationobject#

Expiration options for the hash.

Show expiration

exnumber#

Set expiration time in seconds.

pxnumber#

Set expiration time in milliseconds.

exatnumber#

Set expiration as Unix timestamp in seconds.

pxatnumber#

Set expiration as Unix timestamp in milliseconds.

keepttltrue#

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.

fields{ [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).

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

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

// 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

// 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)

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

// 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" });

// 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"});

// 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()  });

// 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)

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