MongoDB $top Accumulator

Example 1 — Sample Data

Two games, four players each. Notice G1 has a clear high score (99)—perfect for checking $top.

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: $top picks the highest score 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 $top in the next examples.

Example 2 — Top Score in One Game

Goal: for game G1 only, return the highest scorer as a [playerId, score] pair.

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

[ { _id: "G1", winner: [ "PlayerC", 99 ] } ]

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. Keep the leader. $top takes the first document: PlayerC with 99.
5. Shape the result. output: ["$playerId", "$score"] returns a two-value array instead of the whole document.

Example 3 — Top Score per Game

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

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

[
  { _id: "G1", winner: { player: "PlayerC", score: 99 } },
  { _id: "G2", winner: { player: "PlayerD", score: 80 } }
]

How It Works

1. Split by game. Each distinct gameId gets its own group and its own top document.
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 — $top vs $max

Same G1 filter: $max gives the number 99; $top gives the player who scored it.

db.gamescores.aggregate([
  { $match: { gameId: "G1" } },
  {
    $group: {
      _id: "$gameId",
      maxScore: { $max: "$score" },
      winner: {
        $top: {
          sortBy: { score: -1 },
          output: ["$playerId", "$score"]
        }
      }
    }
  }
]);

[
  {
    _id: "G1",
    maxScore: 99,
    winner: [ "PlayerC", 99 ]
  }
]

How It Works

1. $max is a number. It compares the score field alone and returns 99.
2. $top is a record. It ranks documents and returns the shaped winner—PlayerC with 99.
3. Pick by need. Use $max for a single numeric peak; use $top when identity fields matter.
4. Need several winners? Switch to $topN for an array of top-k documents.