MongoDB $isoDayOfWeek Operator

What You’ll Learn

The $isoDayOfWeek operator extracts the weekday as an integer using the ISO 8601 calendar (Monday = 1 through Sunday = 7). Use it in aggregation pipelines to filter weekend orders, group sales by weekday, or label business vs non-business days.

Definition and Usage

In MongoDB’s aggregation framework, the $isoDayOfWeek operator takes a date expression and returns an integer from 1 to 7 following the ISO 8601 standard. Monday = 1, Tuesday = 2, and Sunday = 7. For example, $isoDayOfWeek on ISODate("2024-06-17T00:00:00Z") (a Monday) returns 1.

ISO weekday numbering is common in business reporting, analytics dashboards, and international systems where the week starts on Monday. Pair $isoDayOfWeek with $isoWeek and $isoWeekYear for full ISO calendar analysis.

📝 Syntax

The $isoDayOfWeek operator takes a single date expression:

{ $isoDayOfWeek: <dateExpression> }

Syntax Rules

• Argument — any expression that evaluates to a BSON Date.
• Return value — integer 1 (Monday) through 7 (Sunday) in UTC.
• Null input — returns null when the date is null or missing.
• Use inside $project, $addFields, $match with $expr, or $group.

ISO Weekday Number Reference

• 1 — Monday
• 2 — Tuesday
• 3 — Wednesday
• 4 — Thursday
• 5 — Friday
• 6 — Saturday
• 7 — Sunday

Examples Gallery

Walk through sample order data, extract ISO weekday numbers with $project, filter weekends, and group sales by day of week.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "orderDate": ISODate("2024-06-17T14:30:00Z"), "amount": 120 },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "orderDate": ISODate("2024-06-15T10:00:00Z"), "amount": 85 },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "orderDate": ISODate("2024-06-16T18:45:00Z"), "amount": 200 }
]

db.orders.aggregate([
  {
    $project: {
      orderDate: 1,
      amount: 1,
      isoWeekday: {
        $isoDayOfWeek: "$orderDate"
      }
    }
  }
])

// 2024-06-17 (Monday)    → isoWeekday: 1
// 2024-06-15 (Saturday)  → isoWeekday: 6
// 2024-06-16 (Sunday)    → isoWeekday: 7

db.orders.aggregate([
  {
    $match: {
      $expr: {
        $in: [
          { $isoDayOfWeek: "$orderDate" },
          [6, 7]
        ]
      }
    }
  },
  {
    $project: {
      orderDate: 1,
      amount: 1,
      isoWeekday: {
        $isoDayOfWeek: "$orderDate"
      }
    }
  }
])

// Saturday order  (2024-06-15) → isoWeekday: 6, amount: 85
// Sunday order    (2024-06-16) → isoWeekday: 7, amount: 200
// Monday order is excluded

db.orders.aggregate([
  {
    $project: {
      orderDate: 1,
      amount: 1,
      dayType: {
        $cond: [
          {
            $lte: [
              { $isoDayOfWeek: "$orderDate" },
              5
            ]
          },
          "weekday",
          "weekend"
        ]
      }
    }
  }
])

// Monday (1–5)  → dayType: "weekday"
// Saturday (6)  → dayType: "weekend"
// Sunday (7)    → dayType: "weekend"

db.orders.aggregate([
  {
    $group: {
      _id: {
        $isoDayOfWeek: "$orderDate"
      },
      totalAmount: { $sum: "$amount" },
      orderCount: { $sum: 1 }
    }
  },
  {
    $sort: { _id: 1 }
  }
])

{ "_id": 1, "totalAmount": 120, "orderCount": 1 }  // Monday
{ "_id": 6, "totalAmount": 85,  "orderCount": 1 }  // Saturday
{ "_id": 7, "totalAmount": 200, "orderCount": 1 }  // Sunday

db.orders.aggregate([
  {
    $project: {
      orderDate: 1,
      isoWeekday: {
        $isoDayOfWeek: "$orderDate"
      },
      mongoWeekday: {
        $dayOfWeek: "$orderDate"
      }
    }
  }
])

🚀 Use Cases

• Weekend vs weekday analysis — filter or label orders, logins, or events by ISO business days.
• Sales reporting — group revenue by weekday to spot Monday spikes or Friday dips.
• Scheduling logic — route jobs or notifications differently on Saturdays and Sundays.
• ISO calendar pipelines — combine with $isoWeek and $isoWeekYear for standard week-based reports.

💡 Best Practices