MongoDB $bottomN 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 bottom-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: $bottomN keeps the lowest 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 $bottomN in the next examples.

Example 2 — Three Lowest Scores in One Game

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

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

[
  {
    _id: "G1",
    bottomThree: [
      [ "PlayerB", 33 ],
      [ "PlayerA", 31 ],
      [ "PlayerD", 1 ]
    ]
  }
]

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 end. n: 3 keeps the last three: 33, 31, and 1 (PlayerC’s 99 drops off).
5. Shape each row. output: ["$playerId", "$score"] turns each kept document into a two-value array.

Example 3 — Bottom 3 per Game

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

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

[
  {
    _id: "G1",
    bottomThree: [
      { player: "PlayerB", score: 33 },
      { player: "PlayerA", score: 31 },
      { player: "PlayerD", score: 1 }
    ]
  },
  {
    _id: "G2",
    bottomThree: [
      { player: "PlayerC", score: 66 },
      { player: "PlayerB", score: 14 },
      { player: "PlayerA", score: 10 }
    ]
  }
]

How It Works

1. Split by game. Each distinct gameId gets its own group and its own bottom-3 array.
2. Same ranking rule. Descending score still means “lowest at the bottom” 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 — $bottomN vs $bottom

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

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

[
  {
    _id: "G1",
    worstOnly: [ "PlayerD", 1 ],
    worstThree: [
      [ "PlayerB", 33 ],
      [ "PlayerA", 31 ],
      [ "PlayerD", 1 ]
    ]
  }
]

How It Works

1. Same sort, different size. Both use sortBy: { score: -1 }, so “bottom” means the same ranking.
2. $bottom = one. worstOnly is a single value: PlayerD with score 1.
3. $bottomN = many. worstThree is an array of three pairs ending at that same lowest score.
4. Pick by need. Dashboards that show only the worst player use $bottom; bottom-k lists use $bottomN.