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.
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.
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 ...]
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)
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 ...]
ZADD board 100 alpha 200 beta 300 gamma
ZREM board beta
# (integer) 1
ZREM board delta
# (integer) 0 (not a member)
ZSCORE
Returns the score of member in the sorted set stored at key, as a bulk string.
Syntax: ZSCORE key member
ZADD scores 99.5 alice
ZSCORE scores alice
# "99.5"
ZSCORE scores bob
# (nil)
ZCARD
Returns the number of members in the sorted set stored at key.
Syntax: ZCARD key
ZADD myset 1 a 2 b 3 c
ZCARD myset
# (integer) 3
ZCARD nonexistent
# (integer) 0
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]
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"
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]
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"
WITHSCORES, scores are interleaved after each member name.
Practical example: leaderboard
Sorted sets power leaderboards out of the box — scores keep players ranked automatically:
# 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
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.
