ZADD

Add one or more members to a sorted set, or update their scores

Method Signature

zadd(
  key: string,
  scoreMember: ScoreMember<TData> | ZAddCommandOptions,
  ...scoreMembers: ScoreMember<TData>[]
): Promise<number | null>

Parameters

key · string · required

The key of the sorted set

scoreMember · ScoreMember<TData> | ZAddCommandOptions · required

Either a score-member pair object or options object. If options are provided, at least one score-member pair must follow.

ScoreMember object:

• score (number): The score for the member
• member (TData): The member value to add

scoreMembers · ScoreMember<TData>[]

Additional score-member pairs to add to the sorted set

ZAddCommandOptions

nx · boolean

Only add new elements. Don’t update existing elements. Mutually exclusive with xx.

xx · boolean

Only update existing elements. Don’t add new elements. Mutually exclusive with nx.

gt · boolean

Only update existing elements if the new score is greater than the current score. Mutually exclusive with lt.

lt · boolean

Only update existing elements if the new score is less than the current score. Mutually exclusive with gt.

ch · boolean

Modify the return value to be the number of elements changed (added or updated), instead of only newly added elements.

incr · boolean

When this option is specified, ZADD acts like ZINCRBY. Only one score-member pair can be specified in this mode.

Response

result · number | null

The number of elements added to the sorted set (not including elements already existing for which the score was updated).

When ch option is used, returns the number of elements that were changed (added or updated).

When incr option is used, returns the new score of the member (as a number), or null if the operation was not performed.

Examples

Add a single member

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

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

const result = await redis.zadd('leaderboard', { score: 100, member: 'player1' });
console.log(result); // 1

Add multiple members

const result = await redis.zadd(
  'leaderboard',
  { score: 100, member: 'player1' },
  { score: 85, member: 'player2' },
  { score: 92, member: 'player3' }
);
console.log(result); // 3

Add only if member doesn’t exist (NX)

const result = await redis.zadd(
  'leaderboard',
  { nx: true },
  { score: 100, member: 'player1' }
);
console.log(result); // 1 if added, 0 if already exists

Update only if member exists (XX)

const result = await redis.zadd(
  'leaderboard',
  { xx: true },
  { score: 150, member: 'player1' }
);
console.log(result); // 0 (score updated but not a new member)

Update only if new score is greater (GT)

const result = await redis.zadd(
  'leaderboard',
  { gt: true },
  { score: 120, member: 'player1' }
);
// Only updates if 120 is greater than current score

Increment member score (INCR)

const newScore = await redis.zadd(
  'leaderboard',
  { incr: true },
  { score: 10, member: 'player1' }
);
console.log(newScore); // Current score + 10

Return changed count (CH)

const result = await redis.zadd(
  'leaderboard',
  { ch: true },
  { score: 100, member: 'player1' },
  { score: 85, member: 'player2' }
);
console.log(result); // Number of elements added or updated

Related Commands

• ZINCRBY - Increment the score of a member
• ZSCORE - Get the score of a member
• ZRANGE - Return a range of members
• ZRANK - Get the rank of a member