The $hour operator extracts the hour (0–23) from a BSON Date inside MongoDB aggregation pipelines. Use it for peak-traffic analysis, business-hours filtering, hourly dashboards, and time-of-day reporting.
Date → integer 0–23.
One date argument.
Local hour support.
0–23 in UTC.
Traffic, shifts.
$minute, $dateTrunc.
In MongoDB’s aggregation framework, the $hour operator takes a date expression and returns an integer between 0 and 23. For example, $hour applied to ISODate("2024-06-15T14:30:00Z") returns 14, and ISODate("2024-06-15T02:15:00Z") returns 2.
$hour uses UTC by default. For business-hours logic in a local timezone, use the object form with a timezone option (see Example 4).
The $hour operator takes a date expression, or an object with date and timezone:
{ $hour: <dateExpression> }
// With timezone:
{
$hour: {
date: <dateExpression>,
timezone: <tz>
}
}Date (field, $$NOW, or literal).null when the date is null or missing."America/New_York".$project, $addFields, $set, $match (with $expr), or $group.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date extraction) |
| Arguments | One date expression |
| Return type | Integer (0–23) |
| Timezone support | Yes (object form with timezone) |
| MongoDB version | 3.4+ |
{ $hour: "$loggedAt" }Hour component
{ $hour: ISODate("2024-06-15T14:30:00Z") }Returns 14
{
hour: { $hour: "$eventAt" }
}Add computed field
{
$hour: {
date: "$eventAt",
timezone: "America/New_York"
}
}Local hour
Extract hour values, filter business-hours events, group traffic by hour, and read hours in a local timezone with $hour.
Use a logs collection and compute the hour from loggedAt.
Suppose you have a logs collection with timestamps:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"action": "login",
"loggedAt": ISODate("2024-06-15T09:30:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"action": "purchase",
"loggedAt": ISODate("2024-06-15T14:45:00Z")
}
]Extract the hour component from each timestamp:
db.logs.aggregate([
{
$project: {
action: 1,
loggedAt: 1,
hour: { $hour: "$loggedAt" }
}
}
])09:30 UTC → hour 9.14:45 UTC → hour 14.Business-hours filters, hourly grouping, and timezone-aware extraction.
Find logs between 9:00 and 17:59 UTC using $expr:
db.logs.find({
$expr: {
$and: [
{ $gte: [ { $hour: "$loggedAt" }, 9 ] },
{ $lte: [ { $hour: "$loggedAt" }, 17 ] }
]
}
})Combine $hour with $gte and $lte inside $expr. This matches any event from 9:00 through 17:59 (hour 17 includes 5:00–5:59 PM).
Analyze peak traffic hours across all days:
db.pageviews.aggregate([
{
$group: {
_id: { $hour: "$viewedAt" },
views: { $sum: 1 }
}
},
{ $sort: { "_id": 1 } }
])Grouping by $hour aggregates all days together — useful for “which hour of the day is busiest?” charts. Add $dateTrunc if you need per-day hourly buckets instead.
Extract the hour in Eastern Time rather than UTC:
db.logs.aggregate([
{
$project: {
action: 1,
loggedAt: 1,
hourUtc: { $hour: "$loggedAt" },
hourEastern: {
$hour: {
date: "$loggedAt",
timezone: "America/New_York"
}
}
}
}
])
// loggedAt: 2024-06-15T14:30:00Z
// hourUtc: 14, hourEastern: 10 (EDT)The object form with timezone converts the instant to the specified zone before extracting the hour. Use this when business rules follow local time, not UTC.
$hour WorksThe input expression is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB reads the hour component as an integer 0–23 (UTC or specified timezone).
The number is ready for $match, $group, or charts.
Combine with $minute, $dayOfWeek, and $dateTrunc for richer time reporting.
The $hour operator is a simple way to extract the hour component from BSON dates in MongoDB aggregation pipelines. It is especially useful for peak-traffic charts, business-hours filters, and hourly dashboards.
Remember it uses UTC by default. For local business hours, pass a timezone in the object form. Next in the series: $ifNull.
timezone option for local business-hour logic$gte and $lte for hour ranges$expr when filtering by $hour in find()$dateTrunc when you need hourly date buckets$hour with $dateTrunc hourly bucketing$hour on string dates — parse first with $dateFromString$hourUse these points when extracting hours from dates in MongoDB.
0–23 from a date.
PurposeDate expression.
SyntaxNot a Date.
OutputLocal hour support.
Note0 = midnight UTC.
ImportantMove on to $ifNull for null handling, or review $dateTrunc to bucket dates into hourly periods.
5 people found this page helpful