MongoDB $range Operator

What Is $range?

$range is a MongoDB aggregation expression that builds an array of integers from a start value (inclusive) to an end value (exclusive), with an optional step. Think of it as a number-sequence generator.

$range = [start, start+step, …) until end

{ $range: [ <start>, <end> ] }
{ $range: [ <start>, <end>, <step> ] }

start inclusive · end exclusive
step defaults to 1 · cannot be 0

{ $range: [0, 5] }     → [0, 1, 2, 3, 4]
{ $range: [0, 10, 2] } → [0, 2, 4, 6, 8]
{ $range: [5, 0, -1] } → [5, 4, 3, 2, 1]

How to Use $range in MongoDB

Pick start and end (and step if needed), then attach the array to a field.

1. Choose an expression stage ($addFields or $project).
2. Pass [start, end] — remember end is exclusive.
3. Add a non-zero step for every Nth value or counting down.
4. Optionally $unwind the array to get one document per number.

Pseudocode

start, end, step = evaluate(args)   // step defaults to 1
result = []
i = start

if step > 0:
    while i < end:
        result.push(i)
        i = i + step
else if step < 0:
    while i > end:
        result.push(i)
        i = i + step
else:
    error   // step cannot be 0

emit { ..., field: result }

Cheat Sheet

Keep these facts handy while building number sequences.

Live Preview

Pick a start, end, and step to see the array $range would build.

{ $range: [0, 5] }

start = 0 (inclusive)
end   = 5 (exclusive)
step  = 1

→ [0, 1, 2, 3, 4]

Worked Walkthrough — Seat Numbers

A small room needs seat labels 1 through 5. Because end is exclusive, we call $range with [1, 6].

Want seats: 1, 2, 3, 4, 5

$range: [1, 6]
  start = 1  → include
  next  = 2, 3, 4, 5
  end   = 6  → stop (not included)

result → [1, 2, 3, 4, 5]

If you wrote [1, 5] by mistake:
  → [1, 2, 3, 4]   // missing seat 5

MongoDB Examples

We use one room document. First insert it, then build seat numbers with $range, then show a stepped sequence. Run these in mongosh after inserting the sample data once.

db.rooms.insertOne({
  _id: 1,
  room: "A1",
  seatCount: 5
});

db.rooms.find()

{
  _id: 1,
  room: "A1",
  seatCount: 5
}

seatCount = 5
want labels 1 … 5

$range [1, seatCount + 1]
     = [1, 6]
     → [1, 2, 3, 4, 5]

db.rooms.aggregate([
  {
    $addFields: {
      seats: {
        $range: [1, { $add: ["$seatCount", 1] }]
      }
    }
  }
]);

{
  _id: 1,
  room: "A1",
  seatCount: 5,
  seats: [1, 2, 3, 4, 5]
}

db.rooms.aggregate([
  {
    $addFields: {
      evenIndexes: { $range: [0, 10, 2] }
    }
  }
]);

{
  _id: 1,
  room: "A1",
  seatCount: 5,
  evenIndexes: [0, 2, 4, 6, 8]
}

Performance Notes

Building a short sequence is inexpensive. Cost grows with array length and with $unwind, which multiplies documents.

Key Takeaways