MongoDB $isoDayOfWeek Operator

Example 1 — Sample Data

Imagine three events stored as BSON dates in UTC. We save them in a collection named events.

db.events.insertMany([
  { _id: 1, name: "Kickoff", at: ISODate("2024-01-01T12:00:00Z") },
  { _id: 2, name: "Early UTC", at: ISODate("2024-01-01T02:00:00Z") },
  { _id: 3, name: "Wrap-up", at: ISODate("2024-01-07T12:00:00Z") }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps three documents in events. Run find() to see them:

db.events.find()

[
  { _id: 1, name: "Kickoff", at: ISODate("2024-01-01T12:00:00Z") },
  { _id: 2, name: "Early UTC", at: ISODate("2024-01-01T02:00:00Z") },
  { _id: 3, name: "Wrap-up", at: ISODate("2024-01-07T12:00:00Z") }
]

Read those documents like this:

ISO weekdays (UTC):

  Kickoff   2024-01-01 noon  → Monday → 1
  Early UTC 2024-01-01 02:00 → Monday → 1
  Wrap-up   2024-01-07 noon  → Sunday → 7

Early UTC is useful later: with timezone -05:00 it becomes Sunday.

How It Works

1. Insert once. insertMany adds three event documents with real BSON dates.
2. Use ISODate(...). Strings alone are not valid input for $isoDayOfWeek.
3. find() shows the same shape. What you inserted is what you get back—ready for the next examples.

Example 2 — Weekday in UTC

Goal: add iso_day using the default UTC calendar day.

db.events.aggregate([
  {
    $addFields: {
      iso_day: { $isoDayOfWeek: "$at" }
    }
  }
]);

[
  {
    _id: 1,
    name: "Kickoff",
    at: ISODate("2024-01-01T12:00:00Z"),
    iso_day: 1
  },
  {
    _id: 2,
    name: "Early UTC",
    at: ISODate("2024-01-01T02:00:00Z"),
    iso_day: 1
  },
  {
    _id: 3,
    name: "Wrap-up",
    at: ISODate("2024-01-07T12:00:00Z"),
    iso_day: 7
  }
]

How It Works

1. Read the stored date. "$at" is already a BSON Date.
2. Default zone is UTC. No timezone option → use the UTC calendar day.
3. Map to 1–7. Both Jan 1 events are Monday → 1; Wrap-up is Sunday → 7.
4. Keep all fields. $addFields adds iso_day next to the original document.

Example 3 — Weekday With Timezone

Take Early UTC (2024-01-01T02:00:00Z). In UTC it is Monday; with -05:00 it is still Sunday evening.

db.events.aggregate([
  { $match: { _id: 2 } },
  {
    $addFields: {
      iso_day_utc: { $isoDayOfWeek: "$at" },
      iso_day_minus5: {
        $isoDayOfWeek: {
          date: "$at",
          timezone: "-05:00"
        }
      }
    }
  }
]);

{
  _id: 2,
  name: "Early UTC",
  at: ISODate("2024-01-01T02:00:00Z"),
  iso_day_utc: 1,
  iso_day_minus5: 7
}

How It Works

1. Same stored document. Early UTC from Example 1: 2024-01-01T02:00:00Z.
2. UTC weekday. $isoDayOfWeek: "$at" → Monday → 1.
3. Apply -05:00. Local clock becomes 2023-12-31 21:00 → Sunday → 7.
4. Same stored moment, different day number. Always choose the timezone your report means.