> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HSETEX

> Set hash fields with expiration support.

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

<ParamField body="key" type="string" required>
  The key of the hash.
</ParamField>

<ParamField body="options" type="object">
  Options for conditional setting and expiration.

  <Expandable title="properties">
    <ParamField body="conditional" type="'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
    </ParamField>

    <ParamField body="expiration" type="object">
      Expiration options for the hash.

      <Expandable title="expiration">
        <ParamField body="ex" type="number">
          Set expiration time in seconds.
        </ParamField>

        <ParamField body="px" type="number">
          Set expiration time in milliseconds.
        </ParamField>

        <ParamField body="exat" type="number">
          Set expiration as Unix timestamp in seconds.
        </ParamField>

        <ParamField body="pxat" type="number">
          Set expiration as Unix timestamp in milliseconds.
        </ParamField>

        <ParamField body="keepttl" type="true">
          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.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fields" type="{ [fieldName]: TValue }" required>
  An object of fields and their values to set.
</ParamField>

## Response

<ResponseField type="number" required>
  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).
</ResponseField>

<RequestExample>
  ```ts Basic Example theme={"system"}
  // Set fields with 1 hour expiration
  await redis.hsetex("user:123", { expiration: { ex: 3600 } }, { 
    name: "John", 
    email: "john@example.com" 
  });
  ```

  ```ts With FNX (only if hash doesn't exist) theme={"system"}
  // Set fields only if the hash doesn't exist
  const 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 exists
  const result2 = await redis.hsetex(
    "user:456", 
    { conditional: "FNX" }, 
    { email: "jane@example.com" }
  );
  console.log(result2); // 0
  ```

  ```ts With FXX (only if hash exists) theme={"system"}
  // First create the hash
  await redis.hset("session:abc", { token: "xyz" });

  // Update only if hash exists
  const result = await redis.hsetex(
    "session:abc", 
    { conditional: "FXX" }, 
    { user: "john" }
  );
  console.log(result); // 1 (hash exists, field added)

  // Try on non-existent hash
  const result2 = await redis.hsetex(
    "session:nonexistent", 
    { conditional: "FXX" }, 
    { user: "jane" }
  );
  console.log(result2); // 0 (hash doesn't exist)
  ```

  ```ts With PX (milliseconds) theme={"system"}
  // Set fields with 30 second expiration
  await redis.hsetex("cache:data", { expiration: { px: 30000 } }, { 
    value: "cached data",
    timestamp: Date.now().toString()
  });
  ```

  ```ts With EXAT (Unix timestamp in seconds) theme={"system"}
  // Set expiration to specific timestamp
  const futureTime = Math.floor(Date.now() / 1000) + 7200; // 2 hours from now
  await redis.hsetex("temp:data", { expiration: { exat: futureTime } }, { 
    info: "temporary information" 
  });
  ```

  ```ts With PXAT (Unix timestamp in milliseconds) theme={"system"}
  // Set expiration to specific timestamp in milliseconds
  const futureTime = Date.now() + 300000; // 5 minutes from now
  await redis.hsetex("session:xyz", { expiration: { pxat: futureTime } }, { 
    token: "abc123",
    user: "john"
  });
  ```

  ```ts Combined: Conditional + Expiration theme={"system"}
  // Set fields only if hash doesn't exist, with 1 hour expiration
  await redis.hsetex(
    "user:789", 
    { 
      conditional: "FNX", 
      expiration: { ex: 3600 } 
    }, 
    { 
      name: "Alice",
      email: "alice@example.com",
      created: Date.now().toString()
    }
  );
  ```

  ```ts With KEEPTTL theme={"system"}
  // First set fields with expiration
  await redis.hsetex("cache:data", { expiration: { ex: 300 } }, { 
    value: "cached" 
  });

  // Later update fields while retaining the existing TTL
  const 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)
  ```

  ```ts Without Options theme={"system"}
  // Just set fields without expiration or conditions
  await redis.hsetex("data:simple", undefined, { 
    field1: "value1", 
    field2: "value2" 
  });
  ```
</RequestExample>

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