ZRANGE

Return a range of members in a sorted set

Method Signature

// By index (default)
zrange(
  key: string,
  min: number,
  max: number,
  options?: ZRangeCommandOptions
): Promise<TData>

// By score
zrange(
  key: string,
  min: number | `(${number}` | '-inf' | '+inf',
  max: number | `(${number}` | '-inf' | '+inf',
  options: { byScore: true } & ZRangeCommandOptions
): Promise<TData>

// By lexicographical order
zrange(
  key: string,
  min: `(${string}` | `[${string}` | '-' | '+',
  max: `(${string}` | `[${string}` | '-' | '+',
  options: { byLex: true } & ZRangeCommandOptions
): Promise<TData>

Parameters

key · string · required

The key of the sorted set

min · number | string · required

The minimum range value:

• By index: 0-based index (use negative for reverse indexing, e.g., -1 for last element)
• By score: number, (number (exclusive), -inf, or +inf
• By lex: [member (inclusive), (member (exclusive), - (minimum), or + (maximum)

max · number | string · required

The maximum range value (same format as min)

options · ZRangeCommandOptions

Options to control the range query behavior

ZRangeCommandOptions

byScore · boolean

Query by score range instead of index. Mutually exclusive with byLex.

byLex · boolean

Query by lexicographical range instead of index. All members must have the same score. Mutually exclusive with byScore.

rev · boolean

Reverse the ordering, so elements are returned from highest to lowest score

withScores · boolean

Return scores along with members. The result will be a flat array alternating between members and scores.

offset · number

Skip this many elements before returning results. Must be used together with count.

count · number

Return at most this many elements. Must be used together with offset.

Response

result · TData

An array of members in the specified range.

When withScores is true, returns a flat array alternating between member and score: [member1, score1, member2, score2, ...]

Examples

Get range by index

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
await redis.zadd(
  'leaderboard',
  { score: 100, member: 'player1' },
  { score: 85, member: 'player2' },
  { score: 92, member: 'player3' },
  { score: 78, member: 'player4' }
);

// Get top 3 players (indices 0-2 in descending order)
const top3 = await redis.zrange('leaderboard', 0, 2, { rev: true });
console.log(top3); // ['player1', 'player3', 'player2']

Get all members

// Get all members from lowest to highest score
const all = await redis.zrange('leaderboard', 0, -1);
console.log(all); // ['player4', 'player2', 'player3', 'player1']

Get range with scores

const withScores = await redis.zrange('leaderboard', 0, 2, {
  rev: true,
  withScores: true,
});
console.log(withScores); // ['player1', 100, 'player3', 92, 'player2', 85]

Get members by score range

// Get all players with scores between 80 and 95
const byScore = await redis.zrange('leaderboard', 80, 95, {
  byScore: true,
});
console.log(byScore); // ['player2', 'player3']

Get members by score range (exclusive)

// Get players with scores greater than 80 and less than 95 (exclusive)
const byScoreExclusive = await redis.zrange('leaderboard', '(80', '(95', {
  byScore: true,
});
console.log(byScoreExclusive); // ['player2', 'player3']

Get members with score infinity bounds

// Get all players with scores greater than 90
const highScores = await redis.zrange('leaderboard', 90, '+inf', {
  byScore: true,
});
console.log(highScores); // ['player3', 'player1']

Get members by lexicographical range

// Add members with same score for lex ordering
await redis.zadd(
  'names',
  { score: 0, member: 'alice' },
  { score: 0, member: 'bob' },
  { score: 0, member: 'charlie' },
  { score: 0, member: 'diana' }
);

// Get names from 'b' to 'd' (inclusive)
const byLex = await redis.zrange('names', '[b', '[d', {
  byLex: true,
});
console.log(byLex); // ['bob', 'charlie', 'diana']

Use limit with offset and count

// Get 2 members starting from the 3rd highest score
const paginated = await redis.zrange('leaderboard', 0, '+inf', {
  byScore: true,
  rev: true,
  offset: 2,
  count: 2,
});
console.log(paginated); // 2 members starting from rank 3

Related Commands

• ZADD - Add members to a sorted set
• ZRANK - Get the rank of a member
• ZSCORE - Get the score of a member
• ZCARD - Get the number of members