MongoDB $range Operator

What You’ll Learn

The $range operator generates an array of integers in sequence inside MongoDB aggregation pipelines. Use it to create index lists, month numbers, pagination slots, or any counted sequence without storing it in your data.

Definition and Usage

In MongoDB’s aggregation framework, the $range operator returns an array of integers from a start value up to (but not including) an end value. For example, { $range: [0, 5] } produces [0, 1, 2, 3, 4], and { $range: [0, 10, 2] } produces [0, 2, 4, 6, 8].

This is especially useful when you need a sequence on the fly — calendar months, page numbers, retry counts, or array indexes — without pre-storing those values in documents.

📝 Syntax

The $range operator takes an array with two or three expressions:

{ $range: [ <start>, <end>, <optional non-zero step> ] }

Syntax Rules

• Start — inclusive; the first value in the output array.
• End — exclusive; the sequence stops before this value.
• Step — optional; defaults to 1. Must be non-zero.
• Positive step: start must be less than end (e.g. [0, 5]).
• Negative step: start must be greater than end (e.g. [5, 0, -1]).
• Use inside $project, $addFields, $set, or nested in $map.

Examples Gallery

Generate basic sequences, use custom steps, unwind into rows, and build month calendars from a single config document.

db.samples.aggregate([
  {
    $project: {
      sequence: { $range: [0, 5] }
    }
  }
])

// sequence: [0, 1, 2, 3, 4]

{ "sequence": [0, 1, 2, 3, 4] }

db.samples.aggregate([
  {
    $project: {
      evens: { $range: [0, 10, 2] }
    }
  }
])

// evens: [0, 2, 4, 6, 8]

db.reports.aggregate([
  {
    $project: {
      reportName: 1,
      pageIndexes: { $range: [0, "$pageCount"] }
    }
  },
  { $unwind: "$pageIndexes" },
  {
    $project: {
      reportName: 1,
      page: { $add: [ "$pageIndexes", 1 ] }
    }
  }
])

// pageCount: 3 → pages 1, 2, 3

db.config.aggregate([
  {
    $project: {
      year: 1,
      months: { $range: [1, 13] }
    }
  },
  { $unwind: "$months" },
  {
    $project: {
      year: 1,
      month: "$months"
    }
  }
])

{ "year": 2026, "month": 1 }
{ "year": 2026, "month": 2 }
...
{ "year": 2026, "month": 12 }

db.samples.aggregate([
  {
    $project: {
      countdown: { $range: [5, 0, -1] }
    }
  }
])

// countdown: [5, 4, 3, 2, 1]

db.samples.aggregate([
  {
    $project: {
      squares: {
        $map: {
          input: { $range: [1, 6] },
          as: "n",
          in: { $pow: [ "$$n", 2 ] }
        }
      }
    }
  }
])

// squares: [1, 4, 9, 16, 25]

🚀 Use Cases

• Pagination indexes — generate page numbers from a total count field.
• Calendar expansion — produce month or day sequences for reporting pipelines.
• Test data — create indexed rows without inserting sequence documents.
• Array iteration — feed $map or $reduce with a controlled index range.

💡 Best Practices