> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $range (expression operator)

## Definition

Returns an array whose elements are a generated sequence of numbers. [`$range`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/range.md#mongodb-expression-exp.-range) generates the sequence from the specified starting number by successively incrementing the starting number by the specified step value up to but not including the end point.

[`$range`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/range.md#mongodb-expression-exp.-range) has the following [operator expression syntax:](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-agg-quick-ref-operator-expressions)

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

| Operand | Description |
| --- | --- |
| `<start>` | An integer that specifies the start of the sequence. Can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) that resolves to an integer. |
| `<end>` | An integer that specifies the exclusive upper limit of the sequence. Can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) that resolves to an integer. |
| `<non-zero step>` | Optional. An integer that specifies the increment value. Can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) that resolves to a non-zero integer. Defaults to 1. |

## Behavior

The `<start>` and `<end>` arguments are required and must be integers. The `<non-zero step>` argument is optional, and defaults to `1` if omitted.

| Example | Results |
| --- | --- |
| `{ $range: [ 0, 10, 2 ] }` | `[ 0, 2, 4, 6, 8 ]` |
| `{ $range: [ 10, 0, -2 ] }` | `[ 10, 8, 6, 4, 2 ]` |
| `{ $range: [ 0, 10, -2 ] }` | `[ ]` |
| `{ $range: [ 0, 5 ] }` | `[ 0, 1, 2, 3, 4 ]` |

## Example

The following example uses a collection called `distances` that lists cities along with their distance in miles from San Francisco.

Documents in the `distances` collection:

```javascript
db.distances.insertMany([
   { _id: 0, city: "San Jose", distance: 42 },
   { _id: 1, city: "Sacramento", distance: 88 },
   { _id: 2, city: "Reno", distance: 218 },
   { _id: 3, city: "Los Angeles", distance: 383 }
]);
```

A bicyclist is planning to ride from San Francisco to each city listed in the collection and wants to stop and rest every 25 miles. The following aggregation pipeline operation uses the `$range` operator to determine the stopping points for each trip.

```javascript
db.distances.aggregate([{
    $project: {
        _id: 0,
        city: 1,
        "Rest stops": { $range: [ 0, "$distance", 25 ] }
    }
}])
```

The operation returns the following:

```javascript
{ "city" : "San Jose", "Rest stops" : [ 0, 25 ] }
{ "city" : "Sacramento", "Rest stops" : [ 0, 25, 50, 75 ] }
{ "city" : "Reno", "Rest stops" : [ 0, 25, 50, 75, 100, 125, 150, 175, 200 ] }
{ "city" : "Los Angeles", "Rest stops" : [ 0, 25, 50, 75, 100, 125, 150, 175, 200, 225, 250, 275, 300, 325, 350, 375 ] }
```