Introduction to MongoDB $dateToParts Operator

$dateToParts is one of the date processing operators added in MongoDB 4.0. It can convert dates to corresponding parts such as year, month, day, etc., to enable more flexible data processing and aggregation operations.


The syntax of the $dateToParts operator is as follows:

  $dateToParts: {
    date: <dateExpression>,
    timezone: <tzExpression>,
    iso8601: <boolean>

The date parameter represents the date expression to be converted, which can be a string, a date object, or a date operator such as $toDate or $subtract; the timezone parameter represents the time zone, which can be a string or a numeric time zone offset, such as +08:00 or 28800 (in seconds); the iso8601 parameter represents whether to output the result in ISO 8601 format, and can be a Boolean value with the default of false.

Use Cases

The $dateToParts operator is mainly used to convert dates to different parts, such as year, month, day, etc. It can be used with other date operators to implement more complex date processing logic.

In aggregation operations, the $dateToParts operator is often used to calculate the data volume or statistics within a certain time period. It can easily convert dates to the corresponding parts, and then use the $group and other aggregation operators to perform grouped statistics.


Suppose we have a collection called events, which contains information about multiple events, including the event name, start time, end time, etc. Now, we need to query the specific date information for each event, such as the year, month, day, etc.

Suppose the events collection has the following documents:

{ "_id" : 1, "name" : "Event A", "start_time" : ISODate("2022-01-01T00:00:00Z"), "end_time" : ISODate("2022-01-02T00:00:00Z") }
{ "_id" : 2, "name" : "Event B", "start_time" : ISODate("2022-02-15T00:00:00Z"), "end_time" : ISODate("2022-02-17T00:00:00Z") }

We can use the $dateToParts operator to query the specific date information for each event:[
    $project: {
      name: 1,
      start_year: { $dateToParts: { date: "$start_time", unit: "year" } },
      start_month: { $dateToParts: { date: "$start_time", unit: "month" } },
      start_day: { $dateToParts: { date: "$start_time", unit: "day" } },
      end_year: { $dateToParts: { date: "$end_time", unit: "year" } },
      end_month: { $dateToParts: { date: "$end_time", unit: "month" } },
      end_day: { $dateToParts: { date: "$end_time", unit: "day" } }

After executing the aggregation operations above, the following results will be returned:

{ "_id" : 1, "name" : "Event A", "start_year" : 2022, "start_month" : 1, "start_day" : 1, "end_year" : 2022, "end_month" : 1, "end_day" : 2 }
{ "_id" : 2, "name" : "Event B", "start_year" : 2022, "start_month" : 2, "start_day" : 15, "end_year" : 2022, "end_month" : 2, "end_day" : 17 }


The $dateToParts operator can split a date value into specific parts such as year, month, and day, which is useful for statistical analysis in aggregation operations. In practice, we can choose different units to split the date value based on specific needs and perform filtering, grouping, and calculation operations based on the split results.