From a9dca87886bdeb27e1410a21e7303e72f165df6e Mon Sep 17 00:00:00 2001 From: seesharprun Date: Tue, 9 Dec 2025 11:33:00 -0500 Subject: [PATCH] Add reference files --- .../object-expression/$mergeobjects.md | 198 ++++++++++++++ .../object-expression/$objectToArray.md | 243 ++++++++++++++++++ .../operators/object-expression/$setField.md | 209 +++++++++++++++ 3 files changed, 650 insertions(+) create mode 100644 reference/operators/object-expression/$mergeobjects.md create mode 100644 reference/operators/object-expression/$objectToArray.md create mode 100644 reference/operators/object-expression/$setField.md diff --git a/reference/operators/object-expression/$mergeobjects.md b/reference/operators/object-expression/$mergeobjects.md new file mode 100644 index 0000000..0a45127 --- /dev/null +++ b/reference/operators/object-expression/$mergeobjects.md @@ -0,0 +1,198 @@ +--- +title: $mergeObjects +description: The $mergeObjects operator merges multiple documents into a single document +type: operators +category: object-expression +--- + +# $mergeObjects + +The `$mergeObjects` operator combines multiple documents into a single document. The mergeObjects operation is used in aggregation pipelines to merge fields from different documents or add one or more fields to an existing document. The operator overwrites fields in the target document with fields from the source document when conflicts occur. + +## Syntax + +```javascript +{ + $mergeObjects: [ < document1 > , < document2 > , ...] +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`document1, document2`** | The documents to be merged. The documents can be specified as field paths, subdocuments, or constants. | + +## 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 - Merging documents as an accumulator to group documents by the sales subdocument + +The query merges all sales subdocuments per city for a specific company. + +```javascript +db.stores.aggregate([ + { + $match: { + company: "Fourth Coffee" + } + }, + { + $group: { + _id: "$city", + mergedSales: { + $mergeObjects: "$sales" + } + } + }, + { + $limit: 2 // returns only the first 3 grouped cities + } +]) +``` + +The first two results returned by this query are: + +```json +[ + { + "_id": "Jalonborough", + "mergedSales": { + "totalSales": 45747, + "salesByCategory": [ + { + "categoryName": "Bucket Bags", + "totalSales": 45747 + } + ] + } + }, + { + "_id": "Port Vladimir", + "mergedSales": { + "totalSales": 32000, + "salesByCategory": [ + { + "categoryName": "DJ Speakers", + "totalSales": 24989 + }, + { + "categoryName": "DJ Cables", + "totalSales": 7011 + } + ] + } + } +] +``` diff --git a/reference/operators/object-expression/$objectToArray.md b/reference/operators/object-expression/$objectToArray.md new file mode 100644 index 0000000..68e91a2 --- /dev/null +++ b/reference/operators/object-expression/$objectToArray.md @@ -0,0 +1,243 @@ +--- +title: $objectToArray +description: The objectToArray command is used to transform a document (object) into an array of key-value pairs. +type: operators +category: object-expression +--- + +# $objectToArray + +The `$objectToArray` operator is used to transform a document (object) into an array of key-value pairs. Each key-value pair in the resulting array is represented as a document with `k` and `v` fields. This operator is useful when you need to manipulate or analyze the structure of documents within your collections. + +## Syntax + +```javascript +{ + $objectToArray: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **``** | The document (object) to be transformed into an array of key-value pairs. | + +## 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: Transforming the `location` object + +This query transforms the `location` object into an array of key-value pairs. + +```javascript +db.stores.aggregate([ + { + $project: { + locationArray: { $objectToArray: "$location" } + } + }, + { + $limit: 2 // Limit output to first 5 documents + } +]) +``` + +The first two results returned by this query are: + +```json +[ + { + "_id": "a715ab0f-4c6e-4e9d-a812-f2fab11ce0b6", + "locationArray": [ + { + "k": "lat", + "v": -74.0427 + }, + { + "k": "lon", + "v": 160.8154 + } + ] + }, + { + "_id": "923d2228-6a28-4856-ac9d-77c39eaf1800", + "locationArray": [ + { + "k": "lat", + "v": 61.3945 + }, + { + "k": "lon", + "v": -3.6196 + } + ] + } +] +``` + +### Example 2: Transforming the `salesByCategory` array + +To transform the `salesByCategory` array, first unwind the array and then apply the `$objectToArray` operator. + +```javascript +db.stores.aggregate([ + { $unwind: "$sales.salesByCategory" }, + { + $project: { + salesByCategoryArray: { $objectToArray: "$sales.salesByCategory" } + } + }, + { + $limit: 2 + } +]) +``` + +The first two results returned by this query are: + +```json +[ + { + "_id": "a715ab0f-4c6e-4e9d-a812-f2fab11ce0b6", + "salesByCategoryArray": [ + { + "k": "categoryName", + "v": "Stockings" + }, + { + "k": "totalSales", + "v": 25731 + } + ] + }, + { + "_id": "923d2228-6a28-4856-ac9d-77c39eaf1800", + "salesByCategoryArray": [ + { + "k": "categoryName", + "v": "Lamps" + }, + { + "k": "totalSales", + "v": 19880 + } + ] + } +] +``` + +Converting subdocuments to key-value pairs is often used when you want to dynamically process field names, especially when: +- Building generic pipelines. +- Mapping field names into key-value structures for flexible transformations or further processing. diff --git a/reference/operators/object-expression/$setField.md b/reference/operators/object-expression/$setField.md new file mode 100644 index 0000000..bc53e0b --- /dev/null +++ b/reference/operators/object-expression/$setField.md @@ -0,0 +1,209 @@ +--- +title: $setField +description: The setField command is used to add, update, or remove fields in embedded documents. +type: operators +category: object-expression +--- + +# $setField + +The `$setField` operator is used to add, update, or remove fields in embedded documents. The operator allows for precise manipulation of document fields, which makes it useful for tasks such as updating nested fields, restructuring documents, or even removing fields entirely. + +## Syntax + +```javascript +{ + $setField: { + field: , + input: , + value: + } +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **``** | The document (object) to be transformed into an array of key-value pairs. | +| **``** | The document or field being processed. | +| **``** | The new value to assign to the field. If `value` is `null`, the field is removed.| + +## 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: Updating a nested field + +This query performs a conditional update on nested discount values inside promotion events for the document matching a specific `_id`. + +```javascript +db.stores.updateOne( + { "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4" }, + [ + { + $set: { + "store.promotionEvents": { + $map: { + input: "$store.promotionEvents", + as: "event", + in: { + $setField: { + field: "discounts", + input: "$$event", + value: { + $map: { + input: "$$event.discounts", + as: "discount", + in: { + $cond: { + if: { $eq: ["$$discount.categoryName", "Laptops"] }, + then: { + categoryName: "$$discount.categoryName", + discountPercentage: 18 + }, + else: "$$discount" + } + } + } + } + } + } + } + } + } + } + ] +) +``` + +### Example 2: Removing a field + +This query removes the `totalStaff` field from the `staff` object. + +```javascript +db.collection.updateOne( + { "store.storeId": "12345" }, + [{ + $set: { + "store.staff": { + $setField: { + field: "totalStaff", + input: "$store.staff", + value: null + } + } + } + }] +) +```