diff --git a/reference/operators/miscellaneous-query/$comment.md b/reference/operators/miscellaneous-query/$comment.md new file mode 100644 index 0000000..251c1ef --- /dev/null +++ b/reference/operators/miscellaneous-query/$comment.md @@ -0,0 +1,106 @@ +--- +title: $comment +description: The $comment operator adds a comment to a query to help identify the query in logs and profiler output. +type: operators +category: miscellaneous-query +--- + +# $comment + +The `$comment` operator adds comments to queries to help identify them in logs and profiler output. This is particularly useful for debugging and monitoring database operations. + +## Syntax + +```javascript +{ + $comment: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`string`** | A string containing the comment to be included with the query. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "location": { + "lat": 70.1272, + "lon": 69.7296 + }, + "staff": { + "totalStaff": { + "fullTime": 19, + "partTime": 20 + } + }, + "sales": { + "totalSales": 151864, + "salesByCategory": [ + { + "categoryName": "Sound Bars", + "totalSales": 2120 + }, + { + "categoryName": "Home Theater Projectors", + "totalSales": 45004 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Massive Markdown Mania", + "promotionalDates": { + "startDate": { + "Year": 2023, + "Month": 6, + "Day": 29 + }, + "endDate": { + "Year": 2023, + "Month": 7, + "Day": 9 + } + }, + "discounts": [ + { + "categoryName": "DVD Players", + "discountPercentage": 14 + } + ] + } + ] +} +``` + +### Example 1: Find stores with total sales over 100,000 and add a log comment for reference + +This query retrieves stores with total sales greater than 100,000 and includes a comment for easy identification in logs. + +```javascript +db.stores.find( + { "sales.totalSales": { $gt: 100000 } }, + { name: 1, "sales.totalSales": 1 } +).comment("Query to find high-performing stores") +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "sales": { + "totalSales": 151864 + } + } +] +``` diff --git a/reference/operators/miscellaneous-query/$natural.md b/reference/operators/miscellaneous-query/$natural.md new file mode 100644 index 0000000..1002021 --- /dev/null +++ b/reference/operators/miscellaneous-query/$natural.md @@ -0,0 +1,144 @@ +--- +title: $natural +description: The $natural operator forces the query to use the natural order of documents in a collection, providing control over document ordering and retrieval. +type: operators +category: miscellaneous-query +--- + +# $natural + +The `$natural` operator forces the query to use the natural order of documents in a collection. It can be used in sorting operations to retrieve documents in the order they were inserted or in reverse order. This operator is useful when you need predictable ordering without relying on indexed fields. + +## Syntax + +```javascript +{ + $natural: <1 | -1> +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`1`** | Sort in forward natural order (insertion order). | +| **`-1`** | Sort in reverse natural order (reverse insertion order). | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f", + "name": "First Up Consultants | Bed and Bath Center - South Amir", + "location": { + "lat": 60.7954, + "lon": -142.0012 + }, + "staff": { + "totalStaff": { + "fullTime": 18, + "partTime": 17 + } + }, + "sales": { + "totalSales": 37701, + "salesByCategory": [ + { + "categoryName": "Mattress Toppers", + "totalSales": 37701 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Price Drop Palooza", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 30 + } + }, + "discounts": [ + { + "categoryName": "Bath Accessories", + "discountPercentage": 18 + } + ] + } + ] +} +``` + +### Example 1: Basic Natural Order Sorting + +This query retrieves all stores in the order they were inserted into the collection. + +```javascript +db.stores.find({}).sort({ + $natural: 1 +}) +``` + +### Example 2: Reverse Natural Order + +This query returns all stores in reverse insertion order, with the most recently added documents appearing first. + +```javascript +db.stores.find({}).sort({ + $natural: -1 +}) +``` + +### Example 3: Natural Order with Filtering + +This query filters stores with total sales greater than 50,000 and returns them in natural insertion order. + +```javascript +db.stores.find({ + "sales.totalSales": { + $gt: 50000 + } +}).sort({ + $natural: 1 +}) +``` + +### Example 4: Natural Order with Projection + +This query returns only the store name, total sales, and location coordinates in natural insertion order. + +```javascript +db.stores.find({}, { + name: 1, + "sales.totalSales": 1, + "location.lat": 1, + "location.lon": 1 +}).sort({ $natural: 1 }) +``` + +### Example 5: Natural Order with Limit + +This query returns the first three stores in their natural insertion order. + +```javascript +db.stores.find({}).sort({ + $natural: 1 +}).limit(3) +``` + +## Use Cases + +The `$natural` operator is useful in the following scenarios: + +- Audit trails: When you need to process documents in the order, they were created +- Chronological processing: For time-sensitive data where insertion order matters +- Batch processing: When processing documents in predictable order without indexes +- Debugging: To understand the natural storage order of documents in a collection diff --git a/reference/operators/miscellaneous-query/$rand.md b/reference/operators/miscellaneous-query/$rand.md new file mode 100644 index 0000000..71905f7 --- /dev/null +++ b/reference/operators/miscellaneous-query/$rand.md @@ -0,0 +1,172 @@ +--- +title: $rand +description: The $rand operator generates a random float value between 0 and 1. +type: operators +category: miscellaneous-query +--- + +# $rand + +The `$rand` operator generates a random float value between 0 and 1. This is useful for random sampling of documents or creating random values in aggregation pipelines. + +## Syntax + +```javascript +{ + $rand: {} +} +``` + +## 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: Add a random value + +This query adds a random value to each store document. + +```javascript +db.stores.aggregate([ + { + $project: { + name: 1, + randomValue: { $rand: {} }, + "sales.totalSales": 1 + } + }, + { $limit: 2 } +]) +``` + +The first two results returned by this query are: + +```json +[ + { + "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f", + "name": "First Up Consultants | Bed and Bath Center - South Amir", + "randomValue": 0.7645893472947384, + "sales": { + "totalSales": 37701 + } + }, + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "randomValue": 0.23456789012345678, + "sales": { + "totalSales": 151864 + } + } +] +```