ZSCORE

Get the score associated with a member in a sorted set

Method Signature

zscore(
  key: string,
  member: TData
): Promise<number | null>

Parameters

key · string · required

The key of the sorted set

member · TData · required

The member whose score you want to retrieve

Response

result · number | null

The score of the member as a number.

Returns null if the member does not exist in the sorted set or the key does not exist.

Examples

Get score of a member

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

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

// Add members to a leaderboard
await redis.zadd(
  'leaderboard',
  { score: 100, member: 'player1' },
  { score: 85, member: 'player2' },
  { score: 92, member: 'player3' }
);

// Get player1's score
const score = await redis.zscore('leaderboard', 'player1');
console.log(score); // 100

Handle non-existing member

const score = await redis.zscore('leaderboard', 'nonexistent');
console.log(score); // null

if (score === null) {
  console.log('Player not found in leaderboard');
} else {
  console.log(`Player score: ${score}`);
}

Update score based on current value

// Get current score
const currentScore = await redis.zscore('leaderboard', 'player1');

if (currentScore !== null) {
  // Award bonus points
  const bonusPoints = 50;
  await redis.zadd('leaderboard', {
    score: currentScore + bonusPoints,
    member: 'player1',
  });
  
  console.log(`New score: ${currentScore + bonusPoints}`);
}

Get multiple scores

const players = ['player1', 'player2', 'player3'];

const scores = await Promise.all(
  players.map(player => redis.zscore('leaderboard', player))
);

players.forEach((player, index) => {
  console.log(`${player}: ${scores[index] ?? 'Not found'}`);
});

Calculate score difference

const score1 = await redis.zscore('leaderboard', 'player1');
const score2 = await redis.zscore('leaderboard', 'player2');

if (score1 !== null && score2 !== null) {
  const difference = Math.abs(score1 - score2);
  console.log(`Score difference: ${difference}`);
}

Display member with score and rank

const member = 'player1';

const [score, rank] = await Promise.all([
  redis.zscore('leaderboard', member),
  redis.zrank('leaderboard', member),
]);

if (score !== null && rank !== null) {
  console.log(`${member}:`);
  console.log(`  Score: ${score}`);
  console.log(`  Rank: ${rank + 1}`);
} else {
  console.log(`${member} not found`);
}

Check if score meets threshold

const threshold = 90;
const score = await redis.zscore('leaderboard', 'player1');

if (score !== null && score >= threshold) {
  console.log('Player qualifies for next level!');
} else {
  const needed = threshold - (score ?? 0);
  console.log(`Need ${needed} more points to qualify`);
}

Related Commands

• ZADD - Add or update members in a sorted set
• ZINCRBY - Increment the score of a member
• ZRANK - Get the rank of a member
• ZRANGE - Return a range of members