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 the fields if none of them exist yet
FXX: Only set the fields if all of them already exist

expirationobject#

Expiration options for the given fields. The TTL applies to each field, not to the hash key.

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) of each field being set. Set to true to enable.

fields{ [fieldName]: TValue }required#

An object of fields and their values to set.

Response#

numberrequired

1 if all fields were set, 0 if none were set because the conditional check failed (e.g., conditional: "FNX" but a field already exists, or conditional: "FXX" but a field 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 only if none of them existconst result = await redis.hsetex( "user:456", { conditional: "FNX" }, { name: "Jane", age: "25" });console.log(result); // 1 (no field existed)// Try again - will return 0 since "name" now existsconst result2 = await redis.hsetex( "user:456", { conditional: "FNX" }, { name: "Janet", email: "jane@example.com" });console.log(result2); // 0

// First create the hashawait redis.hset("session:abc", { token: "xyz" });// Update only if the field already existsconst result = await redis.hsetex( "session:abc", { conditional: "FXX" }, { token: "new-token" });console.log(result); // 1 ("token" exists, value updated)// Try with a field that doesn't existconst result2 = await redis.hsetex( "session:abc", { conditional: "FXX" }, { user: "jane" });console.log(result2); // 0 ("user" doesn't exist)

// 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 none of them 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 the field while retaining its existing TTLconst result = await redis.hsetex( "cache:data", { expiration: { keepttl: true } }, { value: "updated" });console.log(result); // 1// The field's TTL is still 300 seconds (or less if time passed)const ttl = await redis.httl("cache:data", "value");console.log(ttl); // e.g., [298]