Skip to main content

​
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
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us