Introduction to MongoDB $dateFromString Operator

$dateFromString is a MongoDB aggregation operator used to convert a string into a date object. It allows specifying the format and timezone of the string to parse it into a date value. This operator is particularly useful when performing date-related aggregation operations.

Syntax

The basic syntax of the $dateFromString operator is as follows:

{
  $dateFromString: {
    dateString: <string>,
    format: <string>,
    timezone: <string>
  }
}

Here, dateString represents the date string to be converted, format represents the format of the date string, and timezone represents the timezone. format and timezone are optional parameters. If they are not specified, MongoDB uses default values.

Use Cases

Using the $dateFromString operator allows converting a string into a date object, enabling further date processing and calculations in aggregation operations, such as calculating date differences, counting data for each month/week/day, and more. Common use cases include:

• Formatting data with different date formats
• Converting string dates into date objects
• Calculating date differences

Examples

Suppose we have a collection called events, containing information about multiple events, including event names, start times, end times, and so on. Now, we need to query event information based on date strings.

Suppose the events collection contains the following documents:

{
  "_id": 1,
  "name": "Event A",
  "start_date": "2022-03-01T10:30:00Z",
  "end_date": "2022-03-01T12:30:00Z"
},
{
  "_id": 2,
  "name": "Event B",
  "start_date": "2022-03-02T09:00:00Z",
  "end_date": "2022-03-02T10:30:00Z"
},
{
  "_id": 3,
  "name": "Event C",
  "start_date": "2022-03-03T15:00:00Z",
  "end_date": "2022-03-03T17:00:00Z"
}

We can use the $dateFromString operator to convert the date strings into date types, and then use the $match operator to perform a query:

db.events.aggregate([
  {
    $addFields: {
      start_date: {
        $dateFromString: {
          dateString: "$start_date",
          format: "%Y-%m-%dT%H:%M:%S%z"
        }
      },
      end_date: {
        $dateFromString: {
          dateString: "$end_date",
          format: "%Y-%m-%dT%H:%M:%S%z"
        }
      }
    }
  },
  {
    $match: {
      start_date: {
        $gte: ISODate("2022-03-02T00:00:00Z"),
        $lte: ISODate("2022-03-03T23:59:59Z")
      }
    }
  }
])

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

{
  "_id": 2,
  "name": "Event B",
  "start_date": ISODate("2022-03-02T09:00:00Z"),
  "end_date": ISODate("2022-03-02T10:30:00Z")
}
{
  "_id": 3,
  "name": "Event C",
  "start_date": ISODate("2022-03-03T15:00:00Z"),
  "end_date": ISODate("2022-03-03T17:00:00Z")
}

Conclusion

The $dateFromString operator can convert date strings to the date format used internally by MongoDB, making it convenient for date operations. This operator is very useful when dealing with date strings from external data sources. However, it should be noted that the formatting string in the $dateFromString operator must match the format of the date string, otherwise the conversion may fail.