MongoDB $isoWeek Operator

Example 1 — Sample Data

Imagine one order placed on 2026-01-12 (a Monday). We save it in a collection named orders.

db.orders.insertOne({
  _id: 1,
  order: "Notebook",
  orderDate: ISODate("2026-01-12T00:00:00Z")
});

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps one document in orders. Run find() to see it:

db.orders.find()

[
  {
    _id: 1,
    order: "Notebook",
    orderDate: ISODate("2026-01-12T00:00:00Z")
  }
]

Read that document like this:

ISO weeks near early 2026:

  Week 2: Jan 5 … Jan 11
  Week 3: Jan 12 … Jan 18  ← our orderDate
                 |
            $isoWeek → 3

How It Works

1. Insert once. insertOne adds a single order document to orders.
2. Store a real Date. ISODate(...) keeps orderDate as a Date, not a string.
3. find() shows the same shape. Ready for $isoWeek next.

Example 2 — ISO Week Number

Goal: add isoWeek as the ISO week number of orderDate.

db.orders.aggregate([
  {
    $addFields: {
      isoWeek: {
        $isoWeek: "$orderDate"
      }
    }
  }
]);

{
  _id: 1,
  order: "Notebook",
  orderDate: ISODate("2026-01-12T00:00:00Z"),
  isoWeek: 3
}

How It Works

1. Read the stored date. MongoDB already has orderDate: 2026-01-12 from Example 1.
2. Apply ISO rules. That Monday falls in ISO week 3 of 2026.
3. Store the number. $addFields writes isoWeek: 3.

Example 3 — With $isoWeekYear

Same order, but also extract the ISO week-year so weekly reports have a full key.

db.orders.aggregate([
  {
    $addFields: {
      isoWeek: { $isoWeek: "$orderDate" },
      isoWeekYear: { $isoWeekYear: "$orderDate" }
    }
  }
]);

{
  _id: 1,
  order: "Notebook",
  orderDate: ISODate("2026-01-12T00:00:00Z"),
  isoWeek: 3,
  isoWeekYear: 2026
}

How It Works

1. Same stored document. Still using orderDate: 2026-01-12 from Example 1.
2. Week + year together. $isoWeekYear supplies the year half of the ISO week key.
3. Easy report label. You can group as 2026-W03 without mixing calendar-year edge cases.