Add reference Markdown: operators/miscellaneous-query

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: <string>
+}
+```
+
+## 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
+    }
+  }
+]
+```

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