How do you build a live top-10 leaderboard in RethinkDB with a single changefeed?

## The problem "Show the current top N, and keep it current" is the canonical real-time UI. Done naively it becomes: run the query, poll every second, re-render. RethinkDB's order-by-limit changefeed collapses that into one subscription. ```javascript r.table('scores') .orderBy({ index: r.desc('score') }) .limit(10) .changes({ includeInitial: true, includeOffsets: true }) .run(conn); ``` ## Why the index is mandatory A changefeed has to decide, for each incoming write, whether the result set changed. For an ordered window that means knowing where the written document falls in the order without re-scanning the table. An index gives the server exactly that. Consequently `orderBy` in a feed must be index-backed — `r.desc('score')` here refers to a secondary index created with `indexCreate('score')`, not to a client-side sort. Sorting an arbitrary in-memory stream and then subscribing to it is not supported, and the query will be rejected rather than silently degrading. ## Changes are changes to the window This is the part candidates get wrong. On a plain table feed, `old_val`/`new_val` describe one document before and after. On an order-by-limit feed they describe the **membership of the window**: - A new document scores high enough to enter the top ten and pushes the tenth-place document out: one change arrives with `new_val` = the entering document and `old_val` = the departing one. - A document already inside the window has its score edited: `old_val` and `new_val` are the two versions of that same document, and its position may move. - A write that lands entirely outside the window — an eleventh-place score improving but still eleventh — produces nothing, because the answer to the query did not change. That last property is the efficiency win: the server filters for you, and a hot table with a stable leaderboard produces almost no traffic. ## Priming the client Without help, a client that subscribes has an empty list and only learns about entries that subsequently change. `includeInitial: true` fixes this: the feed first emits the current members as changes with `old_val` null, then continues into live updates. Because both arrive on one cursor, there is no window between "I read the table" and "I started listening" in which an update can be lost — the classic race in hand-rolled read-then-subscribe code. With `includeStates: true`, the feed also interleaves marker documents carrying a `state` field so the client can tell when the initial batch is finished and the feed has gone live — useful for showing a spinner until the first render is complete. ## Splicing efficiently `includeOffsets: true` is specific to order-by-limit feeds. Each change then carries the old and new positions of the affected document within the window, so a client holding an array of ten items can remove at one index and insert at another instead of rebuilding and re-sorting. For a ten-row leaderboard the saving is trivial; for a large scrolling window rendered in a UI framework that diffs on identity, it is the difference between a smooth list and a full re-render. ## Practical cautions The window is defined by the query, so changing N means opening a new feed. Ties in the ordering key can make membership at the boundary churn — add a deterministic tiebreaker such as a compound index on score plus the primary key if you see the last slot flapping. And the feed inherits every general changefeed limitation: it lives only while the cursor is open, it is served by the shard primary, and on a disconnect the client must resubscribe — with `includeInitial` doing double duty as the resync mechanism.