Introduction to MongoDB $dateFromParts Operator

$dateFromParts is a date operator in MongoDB that can be used to combine the given date components (such as year, month, day, etc.) into a date object. This operator makes it convenient to construct date objects and is very useful in date calculations and date comparison operations.

Syntax

The syntax of the $dateFromParts operator is as follows:

{
  $dateFromParts: {
    year: <expression>,
    month: <expression>,
    day: <expression>,
    hour: <expression>,
    minute: <expression>,
    second: <expression>,
    millisecond: <expression>,
    timezone: <expression>
  }
}

Where year, month, day, hour, minute, second, and millisecond are expressions that represent the date and time components. These expressions can be any MongoDB expressions that produce integer values, such as field references, arithmetic operators, aggregation pipeline expressions, etc.

The timezone parameter is a string expression that represents the time zone to be applied. If this parameter is not specified, the default time zone will be used.

Use Cases

The $dateFromParts operator is typically used in the following scenarios:

• Combining given date components into a date object.
• Using in date calculations and date comparison operations.

Examples

Example 1: Creating a Date Object with $dateFromParts

Assume that we have a collection called orders that contains information about multiple orders, including order numbers, order dates, etc. Now we need to use the $dateFromParts operator to combine the year, month, and day of each order’s order date into a date object.

Suppose the orders collection has the following documents:

{ "_id": 1, "order_no": "202201010001", "order_year": 2022, "order_month": 1, "order_day": 1 }
{ "_id": 2, "order_no": "202201020001", "order_year": 2022, "order_month": 1, "order_day": 2 }

We can use the following aggregation pipeline to create the date object:

db.orders.aggregate([
  {
    $project: {
      order_date: {
        $dateFromParts: {
          year: "$order_year",
          month: "$order_month",
          day: "$order_day"
        }
      }
    }
  }
])

After running the above aggregation pipeline, we get the following result:

{ "_id": 1, "order_date": ISODate("2022-01-01T00:00:00Z") }
{ "_id": 2, "order_date": ISODate("2022-01-02T00:00:00Z") }

Example 2: Calculating Date Difference with $dateFromParts

Assume that we have a collection called events that contains information about multiple events, including event names, start times, end times, etc. Now we need to calculate the duration (in seconds) of each event.

Assuming there is a set of documents in the events collection as follows:

{ "_id": 1, "name": "Event A", "start": { "year": 2022, "month": 2, "day": 1, "hour": 12, "minute": 0, "second": 0 }, "end": { "year": 2022, "month": 2, "day": 2, "hour": 12, "minute": 0, "second": 0 } }
{ "_id": 2, "name": "Event B", "start": { "year": 2022, "month": 3, "day": 1, "hour": 12, "minute": 0, "second": 0 }, "end": { "year": 2022, "month": 3, "day": 1, "hour": 13, "minute": 0, "second": 0 } }
{ "_id": 3, "name": "Event C", "start": { "year": 2022, "month": 4, "day": 1, "hour": 12, "minute": 0, "second": 0 }, "end": { "year": 2022, "month": 4, "day": 3, "hour": 12, "minute": 0, "second": 0 } }

We can use the following aggregation query to calculate the duration of each event:

db.events.aggregate([
  {
    $addFields: {
      duration: {
        $divide: [
          {
            $subtract: [
              {
                $dateFromParts: {
                  year: { $year: "$end_time" },
                  month: { $month: "$end_time" },
                  day: { $dayOfMonth: "$end_time" },
                  hour: { $hour: "$end_time" },
                  minute: { $minute: "$end_time" },
                  second: { $second: "$end_time" }
                }
              },
              {
                $dateFromParts: {
                  year: { $year: "$start_time" },
                  month: { $month: "$start_time" },
                  day: { $dayOfMonth: "$start_time" },
                  hour: { $hour: "$start_time" },
                  minute: { $minute: "$start_time" },
                  second: { $second: "$start_time" }
                }
              }
            ]
          },
          1000
        ]
      }
    }
  }
])

After running the above aggregation operation, the following results will be returned:

{ "_id" : 1, "event_name" : "Event A", "start_time" : ISODate("2022-01-01T00:00:00Z"), "end_time" : ISODate("2022-01-02T12:34:56Z"), "duration" : 131096 }
{ "_id" : 2, "event_name" : "Event B", "start_time" : ISODate("2022-02-01T00:00:00Z"), "end_time" : ISODate("2022-02-03T23:59:59Z"), "duration" : 259199 }

In the above results, the duration field represents the duration of each event in seconds.

Conclusion

In MongoDB, the $dateFromParts operator can be used to create a new date object from given date parts. Its syntax is simple and can accept any number of date part parameters. The