From 4763659c1dcc661ba4ceba72c172eb1529c08570 Mon Sep 17 00:00:00 2001 From: seesharprun Date: Tue, 9 Dec 2025 11:32:53 -0500 Subject: [PATCH] Add reference files --- .../operators/date-expression/$dateadd.md | 227 +++++++++++++++++ .../operators/date-expression/$datediff.md | 209 ++++++++++++++++ .../date-expression/$datefromparts.md | 192 +++++++++++++++ .../date-expression/$datefromstring.md | 231 +++++++++++++++++ .../date-expression/$datesubtract.md | 180 ++++++++++++++ .../operators/date-expression/$datetoparts.md | 223 +++++++++++++++++ .../date-expression/$datetostring.md | 225 +++++++++++++++++ .../operators/date-expression/$datetrunc.md | 212 ++++++++++++++++ .../operators/date-expression/$dayofmonth.md | 166 +++++++++++++ .../operators/date-expression/$dayofweek.md | 166 +++++++++++++ .../operators/date-expression/$dayofyear.md | 170 +++++++++++++ reference/operators/date-expression/$hour.md | 170 +++++++++++++ .../date-expression/$isodayofweek.md | 232 ++++++++++++++++++ .../operators/date-expression/$isoweek.md | 218 ++++++++++++++++ .../operators/date-expression/$isoweekyear.md | 201 +++++++++++++++ .../operators/date-expression/$millisecond.md | 170 +++++++++++++ .../operators/date-expression/$minute.md | 170 +++++++++++++ reference/operators/date-expression/$month.md | 189 ++++++++++++++ .../operators/date-expression/$second.md | 170 +++++++++++++ reference/operators/date-expression/$week.md | 231 +++++++++++++++++ reference/operators/date-expression/$year.md | 220 +++++++++++++++++ 21 files changed, 4172 insertions(+) create mode 100644 reference/operators/date-expression/$dateadd.md create mode 100644 reference/operators/date-expression/$datediff.md create mode 100644 reference/operators/date-expression/$datefromparts.md create mode 100644 reference/operators/date-expression/$datefromstring.md create mode 100644 reference/operators/date-expression/$datesubtract.md create mode 100644 reference/operators/date-expression/$datetoparts.md create mode 100644 reference/operators/date-expression/$datetostring.md create mode 100644 reference/operators/date-expression/$datetrunc.md create mode 100644 reference/operators/date-expression/$dayofmonth.md create mode 100644 reference/operators/date-expression/$dayofweek.md create mode 100644 reference/operators/date-expression/$dayofyear.md create mode 100644 reference/operators/date-expression/$hour.md create mode 100644 reference/operators/date-expression/$isodayofweek.md create mode 100644 reference/operators/date-expression/$isoweek.md create mode 100644 reference/operators/date-expression/$isoweekyear.md create mode 100644 reference/operators/date-expression/$millisecond.md create mode 100644 reference/operators/date-expression/$minute.md create mode 100644 reference/operators/date-expression/$month.md create mode 100644 reference/operators/date-expression/$second.md create mode 100644 reference/operators/date-expression/$week.md create mode 100644 reference/operators/date-expression/$year.md diff --git a/reference/operators/date-expression/$dateadd.md b/reference/operators/date-expression/$dateadd.md new file mode 100644 index 0000000..b5c8dd7 --- /dev/null +++ b/reference/operators/date-expression/$dateadd.md @@ -0,0 +1,227 @@ +--- +title: $dateAdd +description: The $dateAdd operator adds a specified number of time units (day, hour, month etc) to a date. +type: operators +category: date-expression +--- + +# $dateAdd + +The `$dateAdd` operator adds a specified number of time units to a date. It's useful in scenarios where you need to calculate future dates based on a given date and a time interval. + +## Syntax + +```javascript +$dateAdd: { + startDate: , + unit: , + amount: , + timezone: // Optional +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`startDate`** | The starting date for the addition operation. | +| **`unit`** | The unit of time to add. Valid units include: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond`. | +| **`amount`** | The number of units to add. | +| **`timezone`** | Optional. The timezone to use for the operation. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Adding days to a date + +This query projects `eventName` and computes a `newEndDate` by adding 7 days to a date constructed from nested year, month, and day fields. The result is a simplified document showing the event name and its extended end date. + +```javascript +db.stores.aggregate([ + { $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } }, + { $unwind: "$promotionEvents" }, + { $unwind: "$promotionEvents.promotionalDates" }, + { + $project: { + eventName: 1, + newEndDate: { + $dateAdd: { + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.endDate.Year", + month: "$promotionEvents.promotionalDates.endDate.Month", + day: "$promotionEvents.promotionalDates.endDate.Day" + } + }, + unit: "day", + amount: 7 + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "newEndDate": "2024-10-06T00:00:00.000Z" + } +] +``` + +### Example 2: Adding months to a date + +This aggregation query projects the `eventName` and calculates a newStartDate by adding 1 month to a reconstructed start date from nested promotion fields. It helps determine an adjusted event start date based on the original schedule. This query returns each document’s eventName and a newStartDate that is 1 month after the original startDate from nested promotion event data. + +```javascript +db.stores.aggregate([ + { $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } }, + { $unwind: "$promotionEvents" }, + { $unwind: "$promotionEvents.promotionalDates" }, + { + $project: { + eventName: "$promotionEvents.eventName", + newStartDate: { + $dateAdd: { + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + }, + unit: "month", + amount: 1 + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "eventName": "Massive Markdown Mania", + "newStartDate": "2024-10-21T00:00:00.000Z" + } +] +``` diff --git a/reference/operators/date-expression/$datediff.md b/reference/operators/date-expression/$datediff.md new file mode 100644 index 0000000..a62c1e0 --- /dev/null +++ b/reference/operators/date-expression/$datediff.md @@ -0,0 +1,209 @@ +--- +title: $dateDiff +description: The $dateDiff operator calculates the difference between two dates in various units such as years, months, days, etc. +type: operators +category: date-expression +--- + +# $dateDiff + +The `$dateDiff` operator calculates the difference between two dates in various units such as years, months, days, etc. It's useful for determining the duration between two timestamps in your dataset. + +## Syntax + +```javascript +$dateDiff: { + startDate: , + endDate: , + unit: , + timezone: , // Optional + startOfWeek: // Optional +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`startDate`**| The beginning date for the calculation.| +| **`endDate`**| The ending date for the calculation.| +| **`unit`**| The unit of time to measure the difference. Valid values include: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond`.| +| **`timezone`**| Optional. The timezone to use for the calculation.| +| **`startOfWeek`**| Optional. The starting day of the week. Valid values are: `Sunday`, `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`.| + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +## Example 1: Calculate duration in days between two dates + +This query uses `$dateDiff` to compute the number of units (e.g., days, months) between two date fields. It helps measure durations like event length or time since a given date. This query returns the durationInDays along with other fields for the specified `stores` document. + +```javascript +db.stores.aggregate([ + { $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } }, + { $unwind: "$promotionEvents" }, + { + $project: { + eventName: "$promotionEvents.eventName", + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + }, + endDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.endDate.Year", + month: "$promotionEvents.promotionalDates.endDate.Month", + day: "$promotionEvents.promotionalDates.endDate.Day" + } + }, + durationInDays: { + $dateDiff: { + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + }, + endDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.endDate.Year", + month: "$promotionEvents.promotionalDates.endDate.Month", + day: "$promotionEvents.promotionalDates.endDate.Day" + } + }, + unit: "day" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "eventName": "Massive Markdown Mania", + "startDate": "2024-09-21T00:00:00.000Z", + "endDate": "2024-09-29T00:00:00.000Z", + "durationInDays": 8 + } +] +``` diff --git a/reference/operators/date-expression/$datefromparts.md b/reference/operators/date-expression/$datefromparts.md new file mode 100644 index 0000000..5235fed --- /dev/null +++ b/reference/operators/date-expression/$datefromparts.md @@ -0,0 +1,192 @@ +--- +title: $dateFromParts +description: The $dateFromParts operator constructs a date from individual components. +type: operators +category: date-expression +--- + +# $dateFromParts + +The `$dateFromParts` operator constructs a date from individual components such as year, month, day, hour, minute, second, and millisecond. This operator can be useful when dealing with data that stores date components separately. + +## Syntax + +```javascript +{ + $dateFromParts: { + year: < year > , + month: < month > , + day: < day > , + hour: < hour > , + minute: < minute > , + second: < second > , + millisecond: < millisecond > , + timezone: < timezone > + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`year`** | The year component of the date. | +| **`month`** | The month component of the date. | +| **`day`** | The day component of the date. | +| **`hour`** | The hour component of the date. | +| **`minute`** | The minute component of the date. | +| **`second`** | The second component of the date. | +| **`millisecond`** | The millisecond component of the date. | +| **`timezone`** | Optional. A timezone specification. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Constructing a start date + +This query constructs precise startDate and endDate values from nested fields using `$dateFromParts`, then calculates the event duration in days. It helps standardize and analyze event timelines stored in fragmented date formats. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $unwind: "$promotionEvents" + }, + { + $project: { + _id: 1, + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "startDate": "2024-09-21T00:00:00.000Z" + } +] +``` diff --git a/reference/operators/date-expression/$datefromstring.md b/reference/operators/date-expression/$datefromstring.md new file mode 100644 index 0000000..e00d593 --- /dev/null +++ b/reference/operators/date-expression/$datefromstring.md @@ -0,0 +1,231 @@ +--- +title: $dateFromString +description: The $dateDiff operator converts a date/time string to a date object. +type: operators +category: date-expression +--- + +# $dateFromString + +The `$dateFromString` operator is used to convert a date/time string to a date object. This operation can be useful when dealing with string representations of dates that need to be manipulated or queried as date objects. + +## Syntax + +```javascript +{ + $dateFromString: { + dateString: < string > , + format: < string > , + timezone: < string > , + onError: < expression > , + onNull: < expression > + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateString`** | The date/time string to convert to a date object. | +| **`format`** | (Optional) The date format specification of the `dateString`. | +| **`timezone`** | (Optional) The timezone to use to format the date. | +| **`onError`** | (Optional) The value to return if an error occurs while parsing the `dateString`. | +| **`onNull`** | (Optional) The value to return if the `dateString` is `null` or missing. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Convert promotional event dates to ISO dates + +This query constructs full ISO date strings from individual year, month, and day fields using `$concat` and converts them to startDate and endDate using `$dateFromString`. It’s useful when date components are stored separately in documents. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $unwind: "$promotionEvents" + }, + { + $project: { + eventName: "$promotionEvents.eventName", + startDate: { + $dateFromString: { + dateString: { + $concat: [ + { $toString: "$promotionEvents.promotionalDates.startDate.Year" }, + "-", + { + $cond: { + if: { $lt: ["$promotionEvents.promotionalDates.startDate.Month", 10] }, + then: { $concat: ["0", { $toString: "$promotionEvents.promotionalDates.startDate.Month" }] }, + else: { $toString: "$promotionEvents.promotionalDates.startDate.Month" } + } + }, + "-", + { + $cond: { + if: { $lt: ["$promotionEvents.promotionalDates.startDate.Day", 10] }, + then: { $concat: ["0", { $toString: "$promotionEvents.promotionalDates.startDate.Day" }] }, + else: { $toString: "$promotionEvents.promotionalDates.startDate.Day" } + } + } + ] + } + } + }, + endDate: { + $dateFromString: { + dateString: { + $concat: [ + { $toString: "$promotionEvents.promotionalDates.endDate.Year" }, + "-", + { + $cond: { + if: { $lt: ["$promotionEvents.promotionalDates.endDate.Month", 10] }, + then: { $concat: ["0", { $toString: "$promotionEvents.promotionalDates.endDate.Month" }] }, + else: { $toString: "$promotionEvents.promotionalDates.endDate.Month" } + } + }, + "-", + { + $cond: { + if: { $lt: ["$promotionEvents.promotionalDates.endDate.Day", 10] }, + then: { $concat: ["0", { $toString: "$promotionEvents.promotionalDates.endDate.Day" }] }, + else: { $toString: "$promotionEvents.promotionalDates.endDate.Day" } + } + } + ] + } + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "eventName": "Massive Markdown Mania", + "startDate": "2024-09-21T00:00:00.000Z", + "endDate": "2024-09-29T00:00:00.000Z" + } +] +``` diff --git a/reference/operators/date-expression/$datesubtract.md b/reference/operators/date-expression/$datesubtract.md new file mode 100644 index 0000000..f119639 --- /dev/null +++ b/reference/operators/date-expression/$datesubtract.md @@ -0,0 +1,180 @@ +--- +title: $dateSubtract +description: The $dateSubtract operator subtracts a specified amount of time from a date. +type: operators +category: date-expression +--- + +# $dateSubtract + +The `$dateSubtract` operator subtracts a specified time unit from a date. It's useful for calculating past dates or intervals in aggregation pipelines. + +## Syntax + +```javascript +{ + $dateSubtract: { + startDate: , + unit: "", + amount: , + timezone: "" // optional + } +} +``` + +## Parameters + +| Parameter | Description | +| --------------- | ------------------------------------------------ | +| **`startDate`** | The date expression to subtract from. | +| **`unit`** | The time unit to subtract (for example, "day", "hour"). | +| **`amount`** | The amount of the time unit to subtract. | +| **`timezone`** | *(Optional)* Timezone for date calculation. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Subtract seven days + +This query calculates the date one week before the `lastUpdated` field. This query uses `$dateSubtract` to calculate the date exactly seven days before the `storeOpeningDate` timestamp. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + dateOneWeekAgo: { + $dateSubtract: { + startDate: "$storeOpeningDate", + unit: "day", + amount: 7 + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "dateOneWeekAgo": "2024-08-29T11:50:06.549Z" + } +] +``` diff --git a/reference/operators/date-expression/$datetoparts.md b/reference/operators/date-expression/$datetoparts.md new file mode 100644 index 0000000..7abbe7e --- /dev/null +++ b/reference/operators/date-expression/$datetoparts.md @@ -0,0 +1,223 @@ +--- +title: $dateToParts +description: The $dateToParts operator decomposes a date into its individual parts such as year, month, day, and more. +type: operators +category: date-expression +--- + +# $dateToParts + +The `$dateToParts` operator is used to extract individual components (Year, Month, Day, Hour, Minute, Second, Millisecond, etc.) from a date object. The operator is useful for scenarios where manipulation or analysis of specific date parts is required, such as sorting, filtering, or aggregating data based on individual date components. + +## Syntax + +```javascript +$dateToParts: { + date: , + timezone: , // optional + iso8601: // optional +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`date`** | The date expression to extract parts from. | +| **`timezone`** | Optional. Specifies the timezone for the date. Defaults to UTC if not provided. | +| **`iso8601`** | Optional. If true, the operator uses ISO 8601 week date calendar system. Defaults to false. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extracting date parts from a field + +This query uses `$dateToParts` to break down the `lastUpdated` date into components like year, month, day, and time. It helps in analyzing or transforming individual parts of a date for further processing. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + dateParts: { + $dateToParts: { + date: "$lastUpdated" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "dateParts": { + "year": 2024, + "month": 12, + "day": 4, + "hour": 11, + "minute": 50, + "second": 6, + "millisecond": 0 + } + } +] +``` + +### Example 2: Using timezone + +This query extracts the `lastUpdated` timestamp of a specific document and breaks it into date parts like year, month, day, and hour using $dateToParts. Including the "America/New_York" timezone permits the breakdown, reflects the local time instead of UTC. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + datePartsWithTimezone: { + $dateToParts: { + date: "$lastUpdated", + timezone: "America/New_York" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "datePartsWithTimezone": { + "year": 2024, + "month": 12, + "day": 4, + "hour": 6, + "minute": 50, + "second": 6, + "millisecond": 0 + } + } +] +``` diff --git a/reference/operators/date-expression/$datetostring.md b/reference/operators/date-expression/$datetostring.md new file mode 100644 index 0000000..33a0b69 --- /dev/null +++ b/reference/operators/date-expression/$datetostring.md @@ -0,0 +1,225 @@ +--- +title: $dateToString +description: The $dateToString operator converts a date object into a formatted string. +type: operators +category: date-expression +--- + +# $dateToString + +The `$dateToString` operator is used to convert a date object to a string in a specified format. It's commonly used in aggregation pipelines to format date fields for reporting, querying, or display purposes. This operator is highly versatile and allows you to define custom date formats. + +## Syntax + +```javascript +{ + $dateToString: { + format: "", + date: , + timezone: "", + onNull: "" + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`format`** | A string that specifies the format of the output date. | +| **`date`** | The date expression to format. | +| **`timezone`** | (Optional) A string that specifies the timezone. Defaults to UTC if not provided. | +| **`onNull`** | (Optional) A value to return if the `date` field is `null` or missing. | + +## Format Specifiers + +| Symbol | Meaning | +| ------ | ------------------------ | +| `%Y` | Year (four digits) | +| `%m` | Month (two digits) | +| `%d` | Day of month (two digits) | +| `%H` | Hour (24-hour, two digits) | +| `%M` | Minute (two digits) | +| `%S` | Second (two digits) | +| `%L` | Millisecond (three digits) | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Formatting a date field to an ISO-like string + +This query uses `$dateToString` operator to format the `lastUpdated` timestamp into a `YYYY-MM-DD` string. It helps present dates in a readable format suitable for logs, reports, or UI. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + formattedDate: { + $dateToString: { + format: "%Y-%m-%d", + date: "$lastUpdated" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "formattedDate": "2024-12-04" + } +] +``` + +### Example 2: Handling Null Values + +This query formats the nonexistent field `lastUpdated_new` timestamp as a `YYYY-MM-DD` string using `$dateToString`. Considering the date is missing or null, it substitutes a fallback string "No date available" via the onNull option. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + formattedDateOrDefault: { + $dateToString: { + format: "%Y-%m-%d", + date: "$lastUpdated_new", // field doesn't exist + onNull: "No date available" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "formattedDateOrDefault": "No date available" + } +] +``` diff --git a/reference/operators/date-expression/$datetrunc.md b/reference/operators/date-expression/$datetrunc.md new file mode 100644 index 0000000..929a60e --- /dev/null +++ b/reference/operators/date-expression/$datetrunc.md @@ -0,0 +1,212 @@ +--- +title: $dateTrunc +description: The $dateTrunc operator truncates a date to a specified unit. +type: operators +category: date-expression +--- + +# $dateTrunc + +The `$dateTrunc` expression operator truncates a date to the nearest specified unit (for example, hour, day, month). It's useful when working with time-series data or when grouping data by specific time intervals. This operator can be used to simplify and standardize date calculations. + +## Syntax + +```javascript + $dateTrunc: { + date: , + unit: "", + binSize: , // optional + timezone: "", // optional + startOfWeek: "" // optional (used when unit is "week") + } +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`date`** | The date to truncate. | +| **`unit`** | The unit to truncate the date to. Supported values include `year`, `month`, `week`, `day`, `hour`, `minute`, `second`, and `millisecond`. | +| **`binSize`** | (Optional) The size of each bin for truncation. For example, if `binSize` is 2 and `unit` is `hour`, the date is truncated to every 2 hours. | +| **`timezone`** | (Optional) The timezone to use for truncation. Defaults to UTC if not specified. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Truncate to the day + +This query uses `$dateTrunc` to truncate the `lastUpdated` timestamp to the start of the day (00:00:00) in UTC. The operator is useful for grouping or comparing data by calendar day regardless of time. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + truncatedToDay: { + $dateTrunc: { + date: "$lastUpdated", + unit: "day" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "truncatedToDay": "2024-11-29T00:00:00.000Z" + } +] +``` + +### Example 2: Truncate to the start of the week + +This query uses `$dateTrunc` to round the `lastUpdated` timestamp down to the start of its week. It specifies Monday as the start of the week to ensure consistent calendar alignment. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + truncatedToWeek: { + $dateTrunc: { + date: "$lastUpdated", + unit: "week", + startOfWeek: "Monday" + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "truncatedToWeek": "2024-11-25T00:00:00.000Z" + } +] +``` diff --git a/reference/operators/date-expression/$dayofmonth.md b/reference/operators/date-expression/$dayofmonth.md new file mode 100644 index 0000000..eae31ae --- /dev/null +++ b/reference/operators/date-expression/$dayofmonth.md @@ -0,0 +1,166 @@ +--- +title: $dayOfMonth +description: The $dayOfMonth operator extracts the day of the month from a date. +type: operators +category: date-expression +--- + +# $dayOfMonth + +The `$dayOfMonth` operator extracts the day of the month (1–31) from a date value. It's useful for grouping or filtering documents based on the day of the month. + +## Syntax + +```javascript +{ + $dayOfMonth: +} +``` + +## Parameters + +| Parameter | Description | +| ---------------------- | --------------------------------------------------------------- | +| **``** | The date expression from which to extract the day of the month. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract day of the month + +This query uses the `$dayOfMonth` operator to extract the day of the month (1–31) from the `lastUpdated` timestamp and isolates the date component of the field for reporting or grouping. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + dayOfMonth: { $dayOfMonth: "$lastUpdated" } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "dayOfMonth": "4" + } +] +``` diff --git a/reference/operators/date-expression/$dayofweek.md b/reference/operators/date-expression/$dayofweek.md new file mode 100644 index 0000000..5cbd029 --- /dev/null +++ b/reference/operators/date-expression/$dayofweek.md @@ -0,0 +1,166 @@ +--- +title: $dayOfWeek +description: The $dayOfWeek operator extracts the day of the week from a date. +type: operators +category: date-expression +--- + +# $dayOfWeek + +The `$dayOfWeek` operator extracts the day of the week from a date value, where 1 represents Sunday and 7 represents Saturday. It's useful for grouping or filtering documents based on the day of the week. + +## Syntax + +```javascript +{ + $dayOfWeek: +} +``` + +## Parameters + +| Parameter | Description | +| ---------------------- | -------------------------------------------------------------- | +| **``** | The date expression from which to extract the day of the week. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract day of the week + +This query uses the `$dayOfWeek` operator to extract the day of the week from the `lastUpdated` timestamp. The returned value ranges from 1 (Sunday) to 7 (Saturday), based on ISO-8601 ordering. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + dayOfWeek: { $dayOfWeek: "$lastUpdated" } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "dayOfWeek": "4" + } +] +``` diff --git a/reference/operators/date-expression/$dayofyear.md b/reference/operators/date-expression/$dayofyear.md new file mode 100644 index 0000000..5c309c7 --- /dev/null +++ b/reference/operators/date-expression/$dayofyear.md @@ -0,0 +1,170 @@ +--- +title: $dayOfYear +description: The $dayOfYear operator extracts the day of the year from a date. +type: operators +category: date-expression +--- + +# $dayOfYear + +The `$dayOfYear` operator extracts the day of the year from a date value, where 1 represents January 1. It's useful for grouping or filtering documents based on the day of the year. + +## Syntax + +```javascript +{ + $dayOfYear: +} +``` + +## Parameters + +| Parameter | Description | +| ---------------------- | -------------------------------------------------------------- | +| **``** | The date expression from which to extract the day of the year. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract day of the year + +This query uses the `$dayOfYear` operator to extract the ordinal day of the year (1–366) from the `lastUpdated` timestamp. + +```javascript +db.stores.aggregate([ + { + $match: { _id: "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } + }, + { + $project: { + _id: 0, + dayOfYear: { $dayOfYear: "$lastUpdated" } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "dayOfYear": 339 + } +] +``` + +```json +{ "dayOfYear": 339 } +``` diff --git a/reference/operators/date-expression/$hour.md b/reference/operators/date-expression/$hour.md new file mode 100644 index 0000000..fdc0ab3 --- /dev/null +++ b/reference/operators/date-expression/$hour.md @@ -0,0 +1,170 @@ +--- +title: $hour +description: The $hour operator returns the hour portion of a date as a number between 0 and 23. +type: operators +category: date-expression +--- + +# $hour + +The `$hour` operator returns the hour portion of a date as a number between 0 and 23. The operator accepts a date expression that resolves to a Date, Timestamp, or ObjectId. + +## Syntax + +```javascript +{ + $hour: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, Timestamp, or ObjectId. If the expression resolves to null or is missing, `$hour` returns null. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract hour from current date + +This query extracts the `hour` from the current date and time. + +```javascript +db.stores.aggregate([ + { $match: { "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a" } }, + { + $project: { + name: 1, + storeOpeningDate: 1, + currentHour: { $hour: new Date() }, + documentHour: { $hour: "$storeOpeningDate" } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "e6410bb3-843d-4fa6-8c70-7472925f6d0a", + "name": "Relecloud | Toy Collection - North Jaylan", + "storeOpeningDate": "2024-09-05T11:50:06.549Z", + "currentHour": 12, + "documentHour": 11 + } +] +``` diff --git a/reference/operators/date-expression/$isodayofweek.md b/reference/operators/date-expression/$isodayofweek.md new file mode 100644 index 0000000..4bb645d --- /dev/null +++ b/reference/operators/date-expression/$isodayofweek.md @@ -0,0 +1,232 @@ +--- +title: $isoDayOfWeek +description: The $isoDayOfWeek operator returns the weekday number in ISO 8601 format, ranging from 1 (Monday) to 7 (Sunday). +type: operators +category: date-expression +--- + +# $isoDayOfWeek + +The `$isoDayOfWeek` operator returns the weekday number in ISO 8601 format, ranging from 1 (Monday) to 7 (Sunday). The operator accepts a date expression that resolves to a Date, Timestamp, or ObjectId. + +## Syntax + +```javascript +{ + $isoDayOfWeek: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, Timestamp, or ObjectId. If the expression resolves to null or is missing, `$isoDayOfWeek` returns null. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Analyze promotion events by day of week + +This query reviews promotion events to see which days of the week they started on. + +```javascript +db.stores.aggregate([ + { $match: {"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74"} }, + { $unwind: "$promotionEvents" }, + { + $project: { + eventName: "$promotionEvents.eventName", + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + } + } + }, + { + $group: { + _id: { $isoDayOfWeek: "$startDate" }, + eventCount: { $sum: 1 }, + events: { $push: "$eventName" } + } + }, + { + $project: { + _id: 1, + dayName: { + $switch: { + branches: [ + { case: { $eq: ["$_id", 1] }, then: "Monday" }, + { case: { $eq: ["$_id", 2] }, then: "Tuesday" }, + { case: { $eq: ["$_id", 3] }, then: "Wednesday" }, + { case: { $eq: ["$_id", 4] }, then: "Thursday" }, + { case: { $eq: ["$_id", 5] }, then: "Friday" }, + { case: { $eq: ["$_id", 6] }, then: "Saturday" }, + { case: { $eq: ["$_id", 7] }, then: "Sunday" } + ] + } + }, + eventCount: 1, + events: 1 + } + }, + { $sort: { "_id": 1 } } +]) +``` + +This query returns the following results: + +```json +[ + { + "_id": 1, + "eventCount": 1, + "events": ["Super Sale Spectacular"], + "dayName": "Monday" + }, + { + "_id": 2, + "eventCount": 1, + "events": ["Discount Delight Days"], + "dayName": "Tuesday" + }, + { + "_id": 3, + "eventCount": 1, + "events": ["Fantastic Deal Days"], + "dayName": "Wednesday" + }, + { + "_id": 4, + "eventCount": 1, + "events": ["Massive Markdown Mania"], + "dayName": "Thursday" + }, + { + "_id": 6, + "eventCount": 1, + "events": ["Major Bargain Bash"], + "dayName": "Saturday" + }, + { + "_id": 7, + "eventCount": 1, + "events": ["Grand Deal Days"], + "dayName": "Sunday" + } +] +``` diff --git a/reference/operators/date-expression/$isoweek.md b/reference/operators/date-expression/$isoweek.md new file mode 100644 index 0000000..b9ee047 --- /dev/null +++ b/reference/operators/date-expression/$isoweek.md @@ -0,0 +1,218 @@ +--- +title: $isoWeek +description: The $isoWeek operator returns the week number of the year in ISO 8601 format, ranging from 1 to 53. +type: operators +category: date-expression +--- + +# $isoWeek + +The `$isoWeek` operator returns the week number of the year in ISO 8601 format, ranging from 1 to 53. The operator accepts a date expression that resolves to a Date, Timestamp, or ObjectId. In ISO 8601, weeks start on Monday and the first week of the year is the week that contains the first Thursday of the year. + +## Syntax + +```javascript +{ + $isoWeek: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, Timestamp, or ObjectId. If the expression resolves to null or is missing, `$isoWeek` returns null. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Get ISO week number for promotion events + +This query extracts the ISO week number for promotion event start dates. + +```javascript +db.stores.aggregate([ + { $match: {"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74"} }, + { $unwind: "$promotionEvents" }, + { + $project: { + eventName: "$promotionEvents.eventName", + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + } + } + }, + { + $project: { + eventName: 1, + startDate: 1, + isoWeekNumber: { $isoWeek: "$startDate" }, + year: { $year: "$startDate" } + } + } +]) +``` + +This query returns the following results: + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Massive Markdown Mania", + "startDate": "2023-06-29T00:00:00.000Z", + "isoWeekNumber": 26, + "year": 2023 + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Fantastic Deal Days", + "startDate": "2023-09-27T00:00:00.000Z", + "isoWeekNumber": 39, + "year": 2023 + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Discount Delight Days", + "startDate": "2023-12-26T00:00:00.000Z", + "isoWeekNumber": 52, + "year": 2023 + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Super Sale Spectacular", + "startDate": "2024-03-25T00:00:00.000Z", + "isoWeekNumber": 13, + "year": 2024 + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Grand Deal Days", + "startDate": "2024-06-23T00:00:00.000Z", + "isoWeekNumber": 25, + "year": 2024 + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Major Bargain Bash", + "startDate": "2024-09-21T00:00:00.000Z", + "isoWeekNumber": 38, + "year": 2024 + } +] +``` diff --git a/reference/operators/date-expression/$isoweekyear.md b/reference/operators/date-expression/$isoweekyear.md new file mode 100644 index 0000000..c336988 --- /dev/null +++ b/reference/operators/date-expression/$isoweekyear.md @@ -0,0 +1,201 @@ +--- +title: $isoWeekYear +description: The $isoWeekYear operator returns the year number in ISO 8601 format, which can differ from the calendar year for dates at the beginning or end of the year. +type: operators +category: date-expression +--- + +# $isoWeekYear + +The `$isoWeekYear` operator returns the year number in ISO 8601 format. The ISO week-numbering year can differ from the calendar year for dates at the beginning or end of the year. The ISO week year is the year that contains the Thursday of the week in question. + +## Syntax + +```javascript +{ + $isoWeekYear: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, Timestamp, or ObjectId. If the expression resolves to null or is missing, `$isoWeekYear` returns null. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Compare calendar year vs ISO week year + +This query demonstrates the difference between calendar year and ISO week year, especially for dates near year boundaries. + +```javascript +db.stores.aggregate([ + { $match: {_id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74"} }, + { $unwind: "$promotionEvents" }, + { + $project: { + eventName: "$promotionEvents.eventName", + startDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.startDate.Year", + month: "$promotionEvents.promotionalDates.startDate.Month", + day: "$promotionEvents.promotionalDates.startDate.Day" + } + }, + endDate: { + $dateFromParts: { + year: "$promotionEvents.promotionalDates.endDate.Year", + month: "$promotionEvents.promotionalDates.endDate.Month", + day: "$promotionEvents.promotionalDates.endDate.Day" + } + } + } + }, + { + $project: { + eventName: 1, + startDate: 1, + endDate: 1, + startCalendarYear: { $year: "$startDate" }, + startISOWeekYear: { $isoWeekYear: "$startDate" }, + endCalendarYear: { $year: "$endDate" }, + endISOWeekYear: { $isoWeekYear: "$endDate" }, + yearDifference: { + $ne: [{ $year: "$startDate" }, { $isoWeekYear: "$startDate" }] + } + } + }, + { $match: {"eventName": "Discount Delight Days" } } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "eventName": "Discount Delight Days", + "startDate": "2023-12-26T00:00:00.000Z", + "endDate": "2024-01-05T00:00:00.000Z", + "startCalendarYear": 2023, + "startISOWeekYear": Long("2023"), + "endCalendarYear": 2024, + "endISOWeekYear": Long("2024"), + "yearDifference": true + } +] +``` diff --git a/reference/operators/date-expression/$millisecond.md b/reference/operators/date-expression/$millisecond.md new file mode 100644 index 0000000..47194df --- /dev/null +++ b/reference/operators/date-expression/$millisecond.md @@ -0,0 +1,170 @@ +--- +title: $millisecond +description: The $millisecond operator extracts the milliseconds portion from a date value. +type: operators +category: date-expression +--- + +# $millisecond + +The `$millisecond` operator extracts the milliseconds portion from a date value, returning a number between 0 and 999. This operator is useful for precise timestamp analysis and filtering operations that require millisecond-level granularity. + +## Syntax + +```javascript +{ + $millisecond: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, a Timestamp, or an ObjectId. If the expression resolves to `null` or is missing, `$millisecond` returns `null`. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract milliseconds from store opening date + +This query extracts the milliseconds portion from the store opening date. + +```javascript +db.stores.aggregate([ + { $match: {_id: "905d1939-e03a-413e-a9c4-221f74055aac"} }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingMilliseconds: { + $millisecond: "$storeOpeningDate" + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": ISODate("2024-09-26T22:55:25.779Z"), + "openingMilliseconds": 779 + } +] +``` diff --git a/reference/operators/date-expression/$minute.md b/reference/operators/date-expression/$minute.md new file mode 100644 index 0000000..028b078 --- /dev/null +++ b/reference/operators/date-expression/$minute.md @@ -0,0 +1,170 @@ +--- +title: $minute +description: The $minute operator extracts the minute portion from a date value. +type: operators +category: date-expression +--- + +# $minute + +The `$minute` operator extracts the minute portion from a date value, returning a number between 0 and 59. This operator is commonly used for time-based analysis and scheduling operations. + +## Syntax + +```javascript +{ + $minute: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, a Timestamp, or an ObjectId. If the expression resolves to `null` or is missing, `$minute` returns `null`. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract minutes from store opening date + +This query extracts the minute portion from the store opening date to analyze opening time patterns. + +```javascript +db.stores.aggregate([ + { $match: {_id: "905d1939-e03a-413e-a9c4-221f74055aac"} }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingMinute: { + $minute: "$storeOpeningDate" + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": ISODate("2024-09-26T22:55:25.779Z"), + "openingMinute": 55 + } +] +``` diff --git a/reference/operators/date-expression/$month.md b/reference/operators/date-expression/$month.md new file mode 100644 index 0000000..b59492f --- /dev/null +++ b/reference/operators/date-expression/$month.md @@ -0,0 +1,189 @@ +--- +title: $month +description: The $month operator extracts the month portion from a date value. +type: operators +category: date-expression +--- + +# $month + +The `$month` operator extracts the month portion from a date value, returning a number between 1 and 12, where 1 represents January and 12 represents December. This operator is essential for seasonal analysis and monthly reporting. + +## Syntax + +```javascript +{ + $month: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, a Timestamp, or an ObjectId. If the expression resolves to `null` or is missing, `$month` returns `null`. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract month from store opening date + +This query extracts the month portion from the store opening date to analyze seasonal opening patterns. + +```javascript +db.stores.aggregate([ + { $match: {_id: "905d1939-e03a-413e-a9c4-221f74055aac"} }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingMonth: { + $month: "$storeOpeningDate" + }, + openingMonthName: { + $switch: { + branches: [ + { case: { $eq: [{ $month: "$storeOpeningDate" }, 1] }, then: "January" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 2] }, then: "February" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 3] }, then: "March" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 4] }, then: "April" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 5] }, then: "May" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 6] }, then: "June" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 7] }, then: "July" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 8] }, then: "August" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 9] }, then: "September" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 10] }, then: "October" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 11] }, then: "November" }, + { case: { $eq: [{ $month: "$storeOpeningDate" }, 12] }, then: "December" } + ] + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": "2024-12-30T22:55:25.779Z", + "openingMonth": 12, + "openingMonthName": "December" + } +] +``` diff --git a/reference/operators/date-expression/$second.md b/reference/operators/date-expression/$second.md new file mode 100644 index 0000000..de4191e --- /dev/null +++ b/reference/operators/date-expression/$second.md @@ -0,0 +1,170 @@ +--- +title: $second +description: The $second operator extracts the seconds portion from a date value. +type: operators +category: date-expression +--- + +# $second + +The `$second` operator extracts the seconds portion from a date value, returning a number between 0 and 59. This operator is useful for precise timestamp analysis and time-sensitive operations that require second-level granularity. + +## Syntax + +```javascript +{ + $second: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | An expression that resolves to a Date, a Timestamp, or an ObjectId. If the expression resolves to `null` or is missing, `$second` returns `null`. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract seconds from store opening date + +This query extracts the seconds portion from the store opening date for precise timing analysis. + +```javascript +db.stores.aggregate([ + { $match: {_id: "905d1939-e03a-413e-a9c4-221f74055aac"} }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingSecond: { + $second: "$storeOpeningDate" + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": ISODate("2024-12-30T22:55:25.779Z"), + "openingSecond": 25 + } +] +``` diff --git a/reference/operators/date-expression/$week.md b/reference/operators/date-expression/$week.md new file mode 100644 index 0000000..16141d3 --- /dev/null +++ b/reference/operators/date-expression/$week.md @@ -0,0 +1,231 @@ +--- +title: $week +description: The $week operator returns the week number for a date as a value between 0 and 53. +type: operators +category: date-expression +--- + +# $week + +The `$week` operator returns the week number for a date as a value between 0 and 53. Week 0 begins on January 1, and subsequent weeks begin on Sundays. If the date is null or missing, `$week` returns null. + +## Syntax + +The syntax for the `$week` operator is as follows: + +```javascript +{ + $week: +} +``` + +Or with timezone specification + +```javascript +{ + $week: { + date: , + timezone: + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | Any expression that resolves to a Date, Timestamp, or ObjectId. | +| **`timezone`** | Optional. The timezone to use for the calculation. Can be an Olson Timezone Identifier (for example, "America/New_York") or a UTC offset (for example, "+0530"). | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Get week number for store opening date + +This query extracts the week number from the store opening date. + +```javascript +db.stores.aggregate([ + { $match: { _id: "905d1939-e03a-413e-a9c4-221f74055aac" } }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingWeek: { $week: { $toDate: "$storeOpeningDate" } } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": ISODate("2024-12-30T22:55:25.779Z"), + "openingWeek": 52 + } +] +``` + +### Example 2: Group stores by opening week + +This query groups stores by the week they were opened for analysis. + +```javascript +db.stores.aggregate([ + { + $project: { + name: 1, + openingWeek: { $week: { $toDate: "$storeOpeningDate" } }, + openingYear: { $year: { $toDate: "$storeOpeningDate" } } + } + }, + { + $group: { + _id: { week: "$openingWeek", year: "$openingYear" }, + storeCount: { $sum: 1 }, + stores: { $push: "$name" } + } + }, + { $sort: { "_id.year": 1, "_id.week": -1 } }, + { $limit : 3 } ]) +``` + +This query returns the following results: + +```json +[ + { + "_id": { "week": 40, "year": 2021 }, + "storeCount": 1, + "stores": [ "First Up Consultants | Bed and Bath Center - South Amir" ] + }, + { + "_id": { "week": 52, "year": 2024 }, + "storeCount": 1, + "stores": [ "Trey Research | Home Office Depot - Lake Freeda" ] + }, + { + "_id": { "week": 50, "year": 2024 }, + "storeCount": 2, + "stores": [ + "Fourth Coffee | Paper Product Bazaar - Jordanechester", + "Adatum Corporation | Pet Supply Center - West Cassie" + ] + } +] +``` diff --git a/reference/operators/date-expression/$year.md b/reference/operators/date-expression/$year.md new file mode 100644 index 0000000..6af94e1 --- /dev/null +++ b/reference/operators/date-expression/$year.md @@ -0,0 +1,220 @@ +--- +title: $year +description: The $year operator returns the year for a date as a four-digit number. +type: operators +category: date-expression +--- + +# $year + +The `$year` operator returns the year for a date as a four-digit number (for example, 2024). If the date is null or missing, `$year` returns null. + +## Syntax + +The syntax for the `$year` operator is as follows: + +```javascript +{ + $year: +} +``` + +Or with timezone specification + +```javascript +{ + $year: { + date: , + timezone: + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`dateExpression`** | Any expression that resolves to a Date, Timestamp, or ObjectId. | +| **`timezone`** | Optional. The timezone to use for the calculation. Can be an Olson Timezone Identifier (for example, "America/New_York") or a UTC offset (for example, "+0530"). | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Extract year from store opening date + +This query extracts the year when the store was opened. + +```javascript +db.stores.aggregate([ + { $match: { _id: "905d1939-e03a-413e-a9c4-221f74055aac" } }, + { + $project: { + name: 1, + storeOpeningDate: 1, + openingYear: { $year: { $toDate: "$storeOpeningDate" } } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "905d1939-e03a-413e-a9c4-221f74055aac", + "name": "Trey Research | Home Office Depot - Lake Freeda", + "storeOpeningDate": "2024-12-30T22:55:25.779Z", + "openingYear": 2024 + } +] +``` + +### Example 2: Find stores opened in specific year + +This query retrieves all stores that were opened in 2021. + +```javascript +db.stores.aggregate([ + { + $match: { + $expr: { + $eq: [{ $year: { $toDate: "$storeOpeningDate" } }, 2021] + } + } + }, + { + $project: { + name: 1, + city: 1, + openingYear: { $year: { $toDate: "$storeOpeningDate" } }, + storeOpeningDate: 1 + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f", + "city": "South Amir", + "storeOpeningDate": "2021-10-03T00:00:00.000Z", + "name": "First Up Consultants | Bed and Bath Center - South Amir", + "openingYear": 2021 + } +] +```