MongoDB $topN Accumulator

Example 1 — Sample Data

Two games, four players each. Notice G1 has a clear high score (99) and a clear low score (1)—perfect for checking top-3 results.

db.gamescores.insertMany([
  { playerId: "PlayerA", gameId: "G1", score: 31 },
  { playerId: "PlayerB", gameId: "G1", score: 33 },
  { playerId: "PlayerC", gameId: "G1", score: 99 },
  { playerId: "PlayerD", gameId: "G1", score: 1 },
  { playerId: "PlayerA", gameId: "G2", score: 10 },
  { playerId: "PlayerB", gameId: "G2", score: 14 },
  { playerId: "PlayerC", gameId: "G2", score: 66 },
  { playerId: "PlayerD", gameId: "G2", score: 80 }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps 8 documents in gamescores. Run find() to see them:

db.gamescores.find()

[
  { playerId: "PlayerA", gameId: "G1", score: 31 },
  { playerId: "PlayerB", gameId: "G1", score: 33 },
  { playerId: "PlayerC", gameId: "G1", score: 99 },
  { playerId: "PlayerD", gameId: "G1", score: 1 },
  { playerId: "PlayerA", gameId: "G2", score: 10 },
  { playerId: "PlayerB", gameId: "G2", score: 14 },
  { playerId: "PlayerC", gameId: "G2", score: 66 },
  { playerId: "PlayerD", gameId: "G2", score: 80 }
]

Read each document like this:

G1 scores: 99, 33, 31, 1
G2 scores: 80, 66, 14, 10

Next: $topN keeps the highest 3 per game.

How It Works

1. Insert once. The sample command adds 8 documents to gamescores.
2. MongoDB stores fields as written. Each document keeps the same field names and values you inserted.
3. find() shows the same shape. What you inserted is what you get back—ready for $topN in the next examples.

Example 2 — Three Highest Scores in One Game

Goal: for game G1 only, return the three highest scorers as [playerId, score] pairs.

db.gamescores.aggregate([
  { $match: { gameId: "G1" } },
  {
    $group: {
      _id: "$gameId",
      topThree: {
        $topN: {
          n: 3,
          sortBy: { score: -1 },
          output: ["$playerId", "$score"]
        }
      }
    }
  }
]);

[
  {
    _id: "G1",
    topThree: [
      [ "PlayerC", 99 ],
      [ "PlayerB", 33 ],
      [ "PlayerA", 31 ]
    ]
  }
]

How It Works

1. Filter first. $match keeps only G1 documents so the group is small and clear.
2. One bucket. _id: "$gameId" makes a single group labeled "G1".
3. Rank high to low. sortBy: { score: -1 } orders scores as 99 → 33 → 31 → 1.
4. Take the start. n: 3 keeps the first three: 99, 33, and 31 (PlayerD’s 1 drops off).
5. Shape each row. output: ["$playerId", "$score"] turns each kept document into a two-value array.

Example 3 — Top 3 per Game

Goal: same top-3 rule for every gameId, with a projection object instead of tuples.

db.gamescores.aggregate([
  {
    $group: {
      _id: "$gameId",
      topThree: {
        $topN: {
          n: 3,
          sortBy: { score: -1 },
          output: { player: "$playerId", score: "$score" }
        }
      }
    }
  },
  { $sort: { _id: 1 } }
]);

[
  {
    _id: "G1",
    topThree: [
      { player: "PlayerC", score: 99 },
      { player: "PlayerB", score: 33 },
      { player: "PlayerA", score: 31 }
    ]
  },
  {
    _id: "G2",
    topThree: [
      { player: "PlayerD", score: 80 },
      { player: "PlayerC", score: 66 },
      { player: "PlayerB", score: 14 }
    ]
  }
]

How It Works

1. Split by game. Each distinct gameId gets its own group and its own top-3 array.
2. Same ranking rule. Descending score still means “highest at the top” in every group.
3. Friendly objects. output: { player, score } is easier to read in APIs than nested arrays.
4. Stable report order. Final $sort on _id lists G1 before G2 (group order from $group alone is not guaranteed).

Example 4 — $topN vs $top

Same G1 filter and sortBy, two accumulators side by side: one best player vs the best three.

db.gamescores.aggregate([
  { $match: { gameId: "G1" } },
  {
    $group: {
      _id: "$gameId",
      bestOnly: {
        $top: {
          sortBy: { score: -1 },
          output: ["$playerId", "$score"]
        }
      },
      bestThree: {
        $topN: {
          n: 3,
          sortBy: { score: -1 },
          output: ["$playerId", "$score"]
        }
      }
    }
  }
]);

[
  {
    _id: "G1",
    bestOnly: [ "PlayerC", 99 ],
    bestThree: [
      [ "PlayerC", 99 ],
      [ "PlayerB", 33 ],
      [ "PlayerA", 31 ]
    ]
  }
]

How It Works

1. Same sort, different size. Both use sortBy: { score: -1 }, so “top” means the same ranking.
2. $top = one. bestOnly is a single value: PlayerC with score 99.
3. $topN = many. bestThree is an array of three pairs starting at that same highest score.
4. Pick by need. Dashboards that show only the winner use $top; top-k lists use $topN.