Skip to main content
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 ...]
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 ...]
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
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
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]
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]
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:
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.