HGETEX - Upstash Documentation

The HGETEX command returns the values of the specified fields and optionally sets their expiration time or TTL. This allows you to retrieve hash data while managing its lifetime in a single operation.

Arguments

keybodystringrequired

The key of the hash.

optionsbodyobjectrequired

Expiration options for the hash fields. The options are mutually exclusive - you can only use one at a time.

exbodynumber

Set expiration time in seconds. Cannot be used with other expiration options.

pxbodynumber

Set expiration time in milliseconds. Cannot be used with other expiration options.

exatbodynumber

Set expiration as Unix timestamp in seconds. Cannot be used with other expiration options.

pxatbodynumber

Set expiration as Unix timestamp in milliseconds. Cannot be used with other expiration options.

persistbodytrue

Remove expiration from the hash. Must be set to true. Cannot be used with other expiration options.

fieldsbody...string[]required

One or more field names to get.

Response

Record<string, TValue | null> | nullrequired

An object containing the field names and their values in the format {[fieldName: string]: TValue | null}. Returns null for fields that do not exist. If the hash doesn't exist or all fields are non-existent, null is returned.

With EX (seconds)

await redis.hset("user:123", { name: "John", email: "john@example.com" });// Get fields and set expiration to 60 secondsconst result = await redis.hgetex("user:123", { ex: 60 }, "name", "email");console.log(result); // { name: "John", email: "john@example.com" }

With PX (milliseconds)

await redis.hset("session:abc", { token: "xyz123", user: "john" });// Get fields and set expiration to 30000 milliseconds (30 seconds)const result = await redis.hgetex("session:abc", { px: 30000 }, "token", "user");console.log(result); // { token: "xyz123", user: "john" }

With EXAT (Unix timestamp in seconds)

await redis.hset("cache:data", { value: "cached" });// Set expiration to specific timestamp (1 hour from now)const futureTime = Math.floor(Date.now() / 1000) + 3600;const result = await redis.hgetex("cache:data", { exat: futureTime }, "value");console.log(result); // { value: "cached" }

With PXAT (Unix timestamp in milliseconds)

await redis.hset("temp:data", { info: "temporary" });// Set expiration to specific timestamp in millisecondsconst futureTime = Date.now() + 60000; // 1 minute from nowconst result = await redis.hgetex("temp:data", { pxat: futureTime }, "info");console.log(result); // { info: "temporary" }

With PERSIST

await redis.hset("user:456", { name: "Jane" });await redis.expire("user:456", 300); // Set 5 minute expiration// Get fields and remove expirationconst result = await redis.hgetex("user:456", { persist: true }, "name");console.log(result); // { name: "Jane" }// Verify expiration was removedconst ttl = await redis.ttl("user:456");console.log(ttl); // -1 (no expiration)

Without Expiration Options

await redis.hset("data:xyz", { field1: "value1", field2: "value2" });// Just get fields without changing expiration// Pass an empty object or an object with no expiration propertiesconst result = await redis.hgetex("data:xyz", {}, "field1", "field2");console.log(result); // { field1: "value1", field2: "value2" }

Non-existent Fields

await redis.hset("user:789", { name: "Bob" });// Get fields including one that doesn't existconst result = await redis.hgetex("user:789", {}, "name", "email");console.log(result); // { name: "Bob", email: null }

Use Cases

Session Management: Retrieve session data and extend its lifetime
Cache Refresh: Get cached data and update its TTL
Temporary Data: Access temporary data while managing its expiration
Rate Limiting: Fetch rate limit data and reset expiration