From 2c52433fa3ed8c51cafebea6847aa47d6f0d25b7 Mon Sep 17 00:00:00 2001 From: seesharprun Date: Tue, 9 Dec 2025 11:32:47 -0500 Subject: [PATCH] Add reference files --- reference/operators/array-query/$all.md | 189 ++++++++++++++ reference/operators/array-query/$elemmatch.md | 231 +++++++++++++++++ reference/operators/array-query/$size.md | 232 ++++++++++++++++++ 3 files changed, 652 insertions(+) create mode 100644 reference/operators/array-query/$all.md create mode 100644 reference/operators/array-query/$elemmatch.md create mode 100644 reference/operators/array-query/$size.md diff --git a/reference/operators/array-query/$all.md b/reference/operators/array-query/$all.md new file mode 100644 index 0000000..0bce6f9 --- /dev/null +++ b/reference/operators/array-query/$all.md @@ -0,0 +1,189 @@ +--- +title: $all +description: The $all operator helps finding array documents matching all the elements. +type: operators +category: array-query +--- + +# $all + +The `$all` operator is used to select documents where the value of a field is an array that contains all the specified elements. This operator is useful when you need to ensure that an array field contains multiple specified elements, regardless of their order in the array. + +## Syntax + +```javascript +db.collection.find({ + field : { + $all: [ < value1 > , < value2 > ] + } +}) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`field`** | The field to be queried. | +| **` , `** | The values that must all be present in the array field. | + +## 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: Find documents containing all the specified elements in an array + +This query retrieves documents containing both elements `Laptops` and `Smartphones` within `salesByCategory.categoryName` array. + +```javascript +db.stores.find({ + "sales.salesByCategory.categoryName": { + $all: ["Laptops", "Smartphones"] + } +}, { + _id: 1, + "sales.salesByCategory.categoryName": 1 +}).limit(2) +``` + +The first two results returned by this query are: + +```json +[ + { + "_id": "a57511bb-1ea3-4b26-bf0d-8bf928f2bfa8", + "sales": { + "salesByCategory": [ + { + "categoryName": "Smartphones" + }, + { + "categoryName": "Laptops" + } + ] + } + }, + { + "_id": "ca56d696-5208-40c3-aa04-d4e245df44dd", + "sales": { + "salesByCategory": [ + { + "categoryName": "Laptops" + }, + { + "categoryName": "Smartphones" + } + ] + } + } +] +``` diff --git a/reference/operators/array-query/$elemmatch.md b/reference/operators/array-query/$elemmatch.md new file mode 100644 index 0000000..ab54fd5 --- /dev/null +++ b/reference/operators/array-query/$elemmatch.md @@ -0,0 +1,231 @@ +--- +title: $elemMatch +description: The $elemmatch operator returns complete array, qualifying criteria with at least one matching array element. +type: operators +category: array-query +--- + +# $elemMatch + +The `$elemMatch` operator is used to match documents that contain an array field with at least one element that matches all the specified query criteria. This operator is useful when you need to find array documents with specified element. + +## Syntax + +```javascript +db.collection.find({ : { $elemMatch: { , , ... } } }) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`field`** | The field in the document that contains the array to be queried. | +| **`query`** | The conditions that at least one element in the array must satisfy. | + +## 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: Find in an array for specific element among the list of elements + +This query retrieves the first two documents in the `stores` collection that have at least one discount with the category name "DJ Lighting" in their `promotionEvents` array. The query only returns the `_id` and `promotionEvents.discounts` fields for those documents. + +```javascript +db.stores.find({ + "promotionEvents.discounts": { + $elemMatch: { + categoryName: "DJ Lighting" + } + } +}, { + _id: 1, + "promotionEvents.discounts": 1 +}).limit(2) +``` + +This query returns the following results: + +```json +[ + { + "_id": "7954bd5c-9ac2-4c10-bb7a-2b79bd0963c5", + "promotionEvents": [ + { + "discounts": [ + { + "categoryName": "DJ Turntables", + "discountPercentage": 18 + }, + { + "categoryName": "DJ Mixers", + "discountPercentage": 15 + } + ] + }, + { + "discounts": [ + { + "categoryName": "DJ Lighting", + "discountPercentage": 14 + }, + { + "categoryName": "DJ Cases", + "discountPercentage": 20 + } + ] + } + ] + }, + { + "_id": "91de5201-8194-44bf-848f-674e8df8bf5e", + "promotionEvents": [ + { + "discounts": [ + { + "categoryName": "DJ Cases", + "discountPercentage": 6 + }, + { + "categoryName": "DJ Mixers", + "discountPercentage": 14 + } + ] + }, + { + "discounts": [ + { + "categoryName": "DJ Headphones", + "discountPercentage": 19 + }, + { + "categoryName": "DJ Speakers", + "discountPercentage": 13 + } + ] + }, + { + "discounts": [ + { + "categoryName": "DJ Lighting", + "discountPercentage": 12 + }, + { + "categoryName": "DJ Accessories", + "discountPercentage": 6 + } + ] + } + ] + } +] +``` diff --git a/reference/operators/array-query/$size.md b/reference/operators/array-query/$size.md new file mode 100644 index 0000000..6554eb6 --- /dev/null +++ b/reference/operators/array-query/$size.md @@ -0,0 +1,232 @@ +--- +title: $size +description: The $size operator is used to query documents where an array field has a specified number of elements. +type: operators +category: array-query +--- + +# $size + +The `$size` operator is used to query documents where an array field has a specified number of elements. This operator is useful when you need to find documents based on the size of an array field, such as finding documents with some items in a list. + +## Syntax + +```javascript +db.collection.find({ : { $size: } }) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`field`** | The field that contains the array. | +| **`number`** | The number of elements the array should have. | + +## 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: Finding documents with a specific number of elements in an array + +This query retrieves documents from the `stores` collection where the `sales.salesByCategory` array contains exactly seven items. + +```javascript +db.stores.find({ + "sales.salesByCategory": { + $size: 7 + } +}, { + _id: 1, + name: 1, + "sales.salesByCategory": 1 +}).limit(2) +``` + +This query returns the following results: + +```json +[ + { + "_id": "7ed4b356-1290-433e-bd96-bf95f817eaaa", + "name": "Wide World Importers", + "sales": { + "salesByCategory": [ + { + "categoryName": "Ultrabooks", + "totalSales": 31304 + }, + { + "categoryName": "Laptop Accessories", + "totalSales": 10044 + }, + { + "categoryName": "Laptops", + "totalSales": 48851 + }, + { + "categoryName": "Refill Kits", + "totalSales": 9604 + }, + { + "categoryName": "Prepaid Phones", + "totalSales": 28600 + }, + { + "categoryName": "Android Phones", + "totalSales": 4580 + }, + { + "categoryName": "Photo Printers", + "totalSales": 35234 + } + ] + } + }, + { + "_id": "988d2dd1-2faa-4072-b420-b91b95cbfd60", + "name": "Lakeshore Retail", + "sales": { + "salesByCategory": [ + { + "categoryName": "Towel Racks", + "totalSales": 13237 + }, + { + "categoryName": "Washcloths", + "totalSales": 44315 + }, + { + "categoryName": "Face Towels", + "totalSales": 42095 + }, + { + "categoryName": "Toothbrush Holders", + "totalSales": 47912 + }, + { + "categoryName": "Hybrid Mattresses", + "totalSales": 48660 + }, + { + "categoryName": "Napkins", + "totalSales": 31439 + }, + { + "categoryName": "Pillow Cases", + "totalSales": 38833 + } + ] + } + } +] +```