Leaderboards (the sorted set as a ranking).

A sorted set stores members with associated scores and maintains order by score automatically. The leaderboard is one sorted set; each member is a player, each score is that player's points. ZADD is the whole write — a member and a score — and re-running it on an existing member overwrites the score and re-places it in the order. A single score is read with ZSCORE, which is O(1).

The score is the entire ordering. Reading the set high-to-low gives the leader at the top; reading low-to-high gives the trailing player. Nothing else indexes the board. This is the move Codemojex.Board.record/3 makes: it folds the player's best base (new_base = max(old, base)) and writes it straight to the board with Cmd.zadd("cm:<game>:board") |> Cmd.score(new_base, player).

A rank is a player's position in the order. Redis reads it from each end. ZRANK counts low-to-high — the lowest score is rank 0. ZREVRANK counts high-to-low — the highest score is rank 0. For a board where higher is better, ZREVRANK is the one to read: the leader sits at rank 0, the runner-up at rank 1. A rank is 0-based, so “rank 0” is first place. The two are mirrors of one position in the same order; reading either end never changes the set.

To show a player their standing against nearby competitors, read a window of positions either side of their own. First find the player's rank, then read the rank window around it.

The same two reads serve any “around-me” view: ZREVRANK to locate the player's position, then a rank-range read centred on it. The window is a slice of the existing order; the board is unchanged. codemojex's read side is the head-read of this family — Codemojex.Board.top/2 runs ZREVRANGE … 0 (n-1) WITHSCORES for the top-N; an around-me band is the same order read with different bounds.

When two players share a score, a plain sorted set falls back to comparing the members lexicographically — not the order a ranking should hold. A sorted set has no secondary sort key, so encode both the points and the tiebreaker into a single score. For a score achieved at a timestamp, pack the points into the high digits and the inverted timestamp into the low digits.

Higher points always dominate; for equal points, the earlier timestamp ranks higher because it is subtracted from a maximum. The points are recovered by integer division. This is the same score-packing idea the priority queue uses to order equal-priority jobs by arrival, covered in R4.03 · Composite priority scores. One score carries two axes, the high digits dominating the low.

A large board is read a page at a time — each page is a rank range. ZCARD returns the member count, which gives the page count. To read a player's rank and score together in one network round trip, pipeline the two reads.

A “this week” or “today” board is a separate sorted set under a time-keyed name, given a TTL so it expires on its own. Several windows combine with ZUNIONSTORE, whose AGGREGATE option chooses how scores merge — SUM for total points across days, MAX for a personal best, MIN for a best time. Redis 6.2 folded the range commands into a unified ZRANGE with a REV option, so ZRANGE … REV reads the same top-N as the older ZREVRANGE; the ordering is identical, only the spelling changed.

The pattern lands twice: the textbook sorted-set leaderboard, and the one codemojex runs. codemojex is a Telegram emoji-guessing game on the same stack. Its competitive state lives in Valkey, and the leaderboard is exactly this pattern, in the real code. The score is the linear total from Codemojex.Scoring — points = 100 - 20 * d per emoji at distance d, summed over six positions, out of 600. The board is one sorted set per game, keyed cm:<game>:board: Codemojex.Board.record/3 folds the player's best base and writes it with ZADD, and Codemojex.Board.top/2 reads the top-N with ZREVRANGE … WITHSCORES. The rank is never stored.

Each dive takes one move of the leaderboard, in the arc write → read → update: the score in and the rank out, the two read shapes over the order, and how a score change re-places a member while the rank stays computed on read. Read them in order.