> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Sorted set commands in Cache-Pot: ZADD, ZRANGE, ZRANGEBYSCORE

> Reference for Cache-Pot sorted set commands: ZADD, ZREM, ZSCORE, ZCARD, ZRANGE, ZRANGEBYSCORE with WITHSCORES option.

A sorted set is like a set — every member is unique — but each member also carries a floating-point score. Cache-Pot keeps members ordered by score at all times, so you can efficiently retrieve ranges by rank or by score value. Sorted sets are the go-to structure for leaderboards, priority queues, rate-limit windows, and any scenario where you need ordered, deduplicated data.

<Note>
  Scores are 64-bit floats. Members are unique within a sorted set; adding an existing member does not create a duplicate — it updates that member's score instead.
</Note>

***

### ZADD

Adds one or more members to the sorted set stored at `key`, each with an associated score. If a member already exists its score is updated. If `key` does not exist, a new sorted set is created.

**Syntax:** `ZADD key score member [score member ...]`

```redis theme={null}
ZADD leaderboard 1500 alice 2200 bob 1800 carol
# (integer) 3  (three new members added)

ZADD leaderboard 2500 alice
# (integer) 0  (alice existed; score updated to 2500)
```

**Returns:** Integer — the number of members that were newly added (score updates are not counted).

***

### ZREM

Removes one or more members from the sorted set stored at `key`. Members that are not present are silently ignored.

**Syntax:** `ZREM key member [member ...]`

```redis theme={null}
ZADD board 100 alpha 200 beta 300 gamma

ZREM board beta
# (integer) 1

ZREM board delta
# (integer) 0  (not a member)
```

**Returns:** Integer — the number of members that were actually removed.

***

### ZSCORE

Returns the score of `member` in the sorted set stored at `key`, as a bulk string.

**Syntax:** `ZSCORE key member`

```redis theme={null}
ZADD scores 99.5 alice

ZSCORE scores alice
# "99.5"

ZSCORE scores bob
# (nil)
```

**Returns:** Bulk string representing the score, or nil if the member or key does not exist.

***

### ZCARD

Returns the number of members in the sorted set stored at `key`.

**Syntax:** `ZCARD key`

```redis theme={null}
ZADD myset 1 a 2 b 3 c

ZCARD myset
# (integer) 3

ZCARD nonexistent
# (integer) 0
```

**Returns:** Integer — the cardinality of the sorted set, or `0` if the key does not exist.

***

### ZRANGE

Returns members of the sorted set stored at `key`, ordered ascending by score. Indices are zero-based; negative indices count from the end (`-1` is the highest-scored member). Optionally interleaves each member with its score when `WITHSCORES` is specified.

**Syntax:** `ZRANGE key start stop [WITHSCORES]`

```redis theme={null}
ZADD leaderboard 1500 alice 2200 bob 1800 carol

# All members, lowest to highest score
ZRANGE leaderboard 0 -1
# 1) "alice"
# 2) "carol"
# 3) "bob"

# With scores interleaved
ZRANGE leaderboard 0 -1 WITHSCORES
# 1) "alice"
# 2) "1500"
# 3) "carol"
# 4) "1800"
# 5) "bob"
# 6) "2200"

# Top member only
ZRANGE leaderboard -1 -1
# 1) "bob"
```

**Returns:** Array of bulk strings. With `WITHSCORES`, the array is twice as long, alternating member and score strings.

***

### ZRANGEBYSCORE

Returns all members of the sorted set stored at `key` whose score falls between `min` and `max` (both inclusive). Use `-inf` and `+inf` for unbounded ranges. Optionally includes scores with `WITHSCORES`.

**Syntax:** `ZRANGEBYSCORE key min max [WITHSCORES]`

```redis theme={null}
ZADD leaderboard 1500 alice 2200 bob 1800 carol

# Members with score between 1600 and +inf
ZRANGEBYSCORE leaderboard 1600 +inf
# 1) "carol"
# 2) "bob"

# With scores
ZRANGEBYSCORE leaderboard 1600 +inf WITHSCORES
# 1) "carol"
# 2) "1800"
# 3) "bob"
# 4) "2200"

# Full range
ZRANGEBYSCORE leaderboard -inf +inf
# 1) "alice"
# 2) "carol"
# 3) "bob"
```

**Returns:** Array of bulk strings. With `WITHSCORES`, scores are interleaved after each member name.

***

## Practical example: leaderboard

Sorted sets power leaderboards out of the box — scores keep players ranked automatically:

```redis theme={null}
# Record player scores
ZADD leaderboard 1500 alice 2200 bob 1800 carol
# (integer) 3

# Full ranking, lowest to highest
ZRANGE leaderboard 0 -1 WITHSCORES
# alice 1500, carol 1800, bob 2200

# Only players above 1600 points
ZRANGEBYSCORE leaderboard 1600 +inf WITHSCORES
# carol 1800, bob 2200

# alice climbs the board
ZADD leaderboard 2500 alice
# (integer) 0  (updated, not newly added)

ZRANGE leaderboard 0 -1 WITHSCORES
# carol 1800, bob 2200, alice 2500

# Remove a player
ZREM leaderboard carol
# (integer) 1

# Current board size
ZCARD leaderboard
# (integer) 2
```

<Tip>
  To retrieve the top-N players on a leaderboard, use `ZRANGE leaderboard -N -1 WITHSCORES`. Because `-1` is the highest-scored element, this gives you the N leaders in ascending score order. Reverse the result client-side to display highest first.
</Tip>