Skip to content
Tutorials Center
My learning

Topics

Lesson 39 of 42 ยท Projects

Project: Game Leaderboard Service

Build a leaderboard on Redis sorted sets: top lists, around-me rank windows, daily and weekly boards with ZUNIONSTORE, TTL cleanup and tie-breaking.

Leaderboards are the classic Redis showcase, and for a good reason. Doing this in a relational database means sorting millions of rows on every request, or maintaining a rank column that must be rewritten whenever somebody scores. A sorted set does the sorting for you as part of every write, and answers "who is in the top ten?" and "what is my rank?" in logarithmic time.

A real game needs more than one list. Players want the all-time board, today's board and this week's board. They want to see their own place and the players just above and below them, not only the top ten that they will never reach. This project builds all of that: scores that accumulate, the top list with names, an around-me window, daily boards that delete themselves, and a weekly board built from the daily ones with ZUNIONSTORE.

Real Redis cannot run on this page. The code runs against a plain JavaScript emulator that implements the real semantics of ZINCRBY, ZRANGE ... REV, ZREVRANK, ZUNIONSTORE, hashes and expiry, with a fake clock so dates and TTLs are the same on every run. The emulator sorts an array on each query, which is much slower than real Redis's skip list, but the answers are the same.

Three boards, one structure

All time lb:all, never expires.
Daily lb:day:DATE, deletes itself.
Weekly lb:week, built from 7 days.
1 / 2

The data model

  • lb:all is a sorted set: member is the player id, score is the total points. Use ids, not display names, as members: names change, and short ids keep the set small.
  • lb:day:2023-11-14 is one sorted set per UTC day. Every score submission adds to both the all-time board and today's board with ZINCRBY, which is atomic, so two game servers submitting for the same player at the same moment never lose points.
  • players is a hash from id to display name. A leaderboard page shows ten names, so it reads the ten scores from the sorted set and the ten names with a single HMGET.
  • lb:week is derived data. It is the sum of the last seven daily boards, built with ZUNIONSTORE and thrown away after five minutes.

Two details deserve attention. Daily boards clean themselves up: when a day's board is first written, submitScore sets an EXPIRE of 8 days on it. There is no midnight cron job; a new date simply produces a new key, and old keys age out. Eight days (not seven) leaves a day of safety so the weekly board never loses its oldest day mid-calculation.

Ranks are zero-based and ascending by default. ZRANK counts from the lowest score, so the best player has the highest rank number. For a leaderboard you want ZREVRANK, where 0 is the best, and then add one for humans. Likewise ZRANGE board 0 9 REV WITHSCORES returns the top ten.

Scores, top lists and the around-me window

The around-me query is the feature that makes a leaderboard feel personal. It takes two commands: ZREVRANK board player gives the position, and ZRANGE board (rank - 2) (rank + 2) REV WITHSCORES returns the neighbours. At the top of the list the window start is clamped at 0, so rank 1 shows ranks 1 to 3 instead of asking for a negative index (which Redis would interpret as "count from the end").

aroundMe also reports the total from ZCARD and a "top N percent" figure. Both are cheap because a sorted set knows its own size and ranks.

JS Top list, around-me and rank arithmetic

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at the tie at the end, and at ranks 4 and 5 in the first output (Hana and Gus both have 3200). When scores are equal, a sorted set orders members by their bytes; with REV the order is reversed, so bo comes before ana. That is stable, but it is arbitrary from a player's point of view: the player who reached the score first should win. The standard fix is to encode time into the score. Because scores are 64-bit floats that represent integers exactly up to about 9 quadrillion, you can store points * 1_000_000 + (999_999 - secondsSinceSeasonStart). More points always win, and for equal points the earlier achiever has the larger low part and therefore ranks higher. Decode the points for display with Math.floor(score / 1_000_000). This only works if each submission replaces the score (ZADD), because ZINCRBY would add the time component repeatedly. Read the score back, add the points in your code, and write the encoded total with ZADD inside a Lua script, or keep a separate best-score game mode that uses ZADD GT.

ZINCRBY is the right tool for accumulating points. For a best score board ("highest single run") use ZADD board GT score player: with GT Redis only updates a member whose new score is greater, so a worse run never overwrites a better one.

Daily and weekly boards with TTL rollover

A weekly board could be maintained by writing every score to a third sorted set, but then the set must be reset on Monday morning, an operation that races with players who are still submitting scores. A neater idea is to compute the week from the days.

weeklyBoard checks whether lb:week exists. If not, it sums the last seven daily boards with ZUNIONSTORE lb:week 7 day1 ... day7 and sets a five-minute expiry. Days without a key (nobody played, or the key expired) count as empty sets. The result is a cache with a TTL: for five minutes every request reads the ready board, then the first request after that rebuilds it. Notice the order: ZUNIONSTORE creates the destination key from scratch, which removes any previous TTL, so the EXPIRE has to come after it.

ZUNIONSTORE touches every member of every input, so on a game with millions of daily players it is expensive. The five-minute cache keeps it off the request path. For truly huge boards, run the union from a scheduled job and let requests only read. You can also pass WEIGHTS to make recent days count more than old ones.

The second TryIt plays nine days of a game. Each day most players submit a score. After day 7 the weekly board is built and served from the cache; after day 9 the oldest daily board has expired, and a rebuilt weekly board covers a different seven-day window.

JS Daily boards, a weekly union and TTL rollover

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the last block of output. The oldest daily board is gone, because its eight days ran out, with no cleanup code of ours involved. The weekly board had expired long before (five minutes after day 7), so the first request after the rollover rebuilt it from the seven newest daily keys. Meanwhile the all-time board never expires, so lifetime totals stay intact.

Production notes

  • Paging. ZRANGE board 0 49 REV, then 50 99 REV and so on. Deep pages are fine, but on a board with tens of millions of members consider capping how deep players can scroll.
  • Friends boards. Per-player friend lists can be intersected with the global board: ZINTERSTORE against a set of friend ids, or read the friends' scores with ZMSCORE and sort in the application.
  • Huge boards. One sorted set with 100 million members is a big key (see performance and latency). Shard by region or season, and move old seasons to a database.
  • Anti-cheat. Never let clients submit points directly. Scores should come from your game servers, and a suspicious player can be removed with ZREM.
  • Season end. Rename or archive the board (RENAME lb:all lb:season:12) and let a new lb:all start empty.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command gives the position of a player counted from the best score, starting at 0?

    ZRANK counts from the lowest score. ZREVRANK counts from the highest, so 0 is the leader. Add 1 for display.
  2. 2. Why does submitScore use ZINCRBY instead of reading the score, adding points and writing it back?

    A read-modify-write in application code could lose an update when two servers run it at once. ZINCRBY adds inside Redis in one step.
  3. 3. How do you build a weekly board from daily boards?

    ZUNIONSTORE sums the scores of the same member across the daily sets. The result is derived data, so it gets a TTL and is rebuilt on demand.
  4. 4. Why must EXPIRE on the weekly board come after ZUNIONSTORE?

    The destination key is replaced by a brand-new key, which has no expiry until you set one.
  5. 5. Two players have the same score. What decides their order, and how can you make the earlier achiever win?

    Equal scores are ordered by member bytes. Putting a descending time component in the low digits of the score makes the earlier achiever rank higher.

Summary

  • Keep one sorted set per leaderboard, with player ids as members and points as scores, and a hash for display names.
  • ZINCRBY accumulates points atomically; ZADD GT keeps a best score; ZRANGE ... REV WITHSCORES reads the top list.
  • Around-me is ZREVRANK plus a clamped ZRANGE ... REV window; the percentile is rank divided by ZCARD.
  • Daily boards get an EXPIRE when first written, so old days disappear without a cron job.
  • Build the weekly board with ZUNIONSTORE over the daily boards, cache it with a short TTL, and set that TTL after the union.
  • Equal scores sort by member bytes; encode a time component in the score if the earlier achiever should win.

Next, test your knowledge across the whole track: Practice Exercises with Solutions.