set

Set the string value of a key

Description

Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful SET operation.

Syntax

redis.set<TData>(
  key: string,
  value: TData,
  opts?: SetCommandOptions
): Promise<TData | "OK" | null>

Parameters

key · string · required

The key to set

value · TData · required

The value to store. Can be a string, number, object, or any serializable data

opts · SetCommandOptions

Optional configuration for the SET command

Show properties

ex · number

Set the specified expire time, in seconds (a positive integer)

px · number

Set the specified expire time, in milliseconds (a positive integer)

exat · number

Set the specified Unix time at which the key will expire, in seconds (a positive integer)

pxat · number

Set the specified Unix time at which the key will expire, in milliseconds (a positive integer)

nx · boolean

Only set the key if it does not already exist

xx · boolean

Only set the key if it already exists

keepTtl · boolean

Retain the time to live associated with the key

get · boolean

Return the old string stored at key, or null if key did not exist

Type Parameters

TData · type

The type of the value being stored

Returns

result · TData | 'OK' | null

• Returns "OK" if SET was executed correctly
• Returns null if the SET operation was not performed (due to nx or xx conditions)
• Returns the old value if the get option was specified

Examples

Basic Usage

import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: 'https://your-redis-url.upstash.io',
  token: 'your-token'
});

// Simple string set
await redis.set('greeting', 'Hello, World!');
// Returns: "OK"

// Set a number
await redis.set('counter', 42);
// Returns: "OK"

Set with Expiration

// Expire in 60 seconds
await redis.set('session:abc', 'user-data', { ex: 60 });

// Expire in 5000 milliseconds
await redis.set('temp:key', 'value', { px: 5000 });

// Expire at specific Unix timestamp (seconds)
const expirationTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
await redis.set('token', 'secret-token', { exat: expirationTime });

// Expire at specific Unix timestamp (milliseconds)
const expirationTimeMs = Date.now() + 3600000; // 1 hour from now
await redis.set('token', 'secret-token', { pxat: expirationTimeMs });

Conditional Set

// Only set if key doesn't exist (SET NX)
const result1 = await redis.set('key', 'value', { nx: true });
console.log(result1); // "OK" if key didn't exist, null otherwise

// Only set if key exists (SET XX)
const result2 = await redis.set('key', 'new-value', { xx: true });
console.log(result2); // "OK" if key existed, null otherwise

Set and Get Old Value

// Set initial value
await redis.set('score', 100);

// Set new value and get the old one
const oldValue = await redis.set('score', 200, { get: true });
console.log(oldValue); // 100

Working with Objects

interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: 'Alice',
  email: '[e-mail]'
};

// Store object with 1 hour expiration
await redis.set('user:1', user, { ex: 3600 });

Keep TTL

// Set a key with expiration
await redis.set('key', 'value1', { ex: 300 }); // 5 minutes

// Update the value but keep the remaining TTL
await redis.set('key', 'value2', { keepTtl: true });
// The key still has the same remaining TTL from the first SET

Notes

• The ex, px, exat, pxat, and keepTtl options are mutually exclusive
• The nx and xx options are mutually exclusive
• When using the get option, the command returns the old value instead of "OK"

Related Commands

• get - Get the value of a key
• mset - Set multiple keys to multiple values

Redis Documentation

For more information, see the Redis SET documentation.