From f428d08b648fa2384723b54d6ecf0048324297f2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 8 Dec 2025 16:17:14 +0000 Subject: [PATCH] sync: copying file post transformation from azure_database_pr @ 58d0fb26c03a535f8d669f492448c40e2fc836ce --- articles/operators/array-query/$all.md | 137 +++++++++++++ articles/operators/array-query/$elemmatch.md | 187 ++++++++++++++++++ articles/operators/array-query/$size.md | 190 +++++++++++++++++++ articles/operators/array-query/TOC.yml | 6 + 4 files changed, 520 insertions(+) create mode 100644 articles/operators/array-query/$all.md create mode 100644 articles/operators/array-query/$elemmatch.md create mode 100644 articles/operators/array-query/$size.md create mode 100644 articles/operators/array-query/TOC.yml diff --git a/articles/operators/array-query/$all.md b/articles/operators/array-query/$all.md new file mode 100644 index 0000000..d98f0de --- /dev/null +++ b/articles/operators/array-query/$all.md @@ -0,0 +1,137 @@ +--- + title: $all + titleSuffix: Overview of the $all operator in DocumentDB + description: The $all operator helps finding array documents matching all the elements. +--- + +# $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({ : { $all: [ , ... ] } }) +``` + +## 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": "a57511bb-1ea3-4b26-bf0d-8bf928f2bfa8", + "name": "Wide World Importers", + "location": { + "lat": 68.6378, + "lon": -145.2852 + }, + "staff": { + "totalStaff": { + "fullTime": 1, + "partTime": 5 + } + }, + "sales": { + "totalSales": 23399, + "salesByCategory": [ + { + "categoryName": "Smartphones", + "totalSales": 5231 + }, + { + "categoryName": "Laptops", + "totalSales": 18168 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2023, + "Month": 5, + "Day": 17 + }, + "endDate": { + "Year": 2023, + "Month": 5, + "Day": 25 + } + }, + "discounts": [ + { + "categoryName": "Video Games", + "discountPercentage": 20 + }, + { + "categoryName": "Tablets", + "discountPercentage": 18 + } + ] + } + ], + "tag": [ + "#ShopLocal", + "#FashionStore", + "#SeasonalSale", + "#FreeShipping", + "#MembershipDeals" + ] +} +``` + +### Example 1: Find documents containing all the specified elements in an array + +The example allows querying the `stores` collection to find 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) +``` + +This query returns the following results. + +```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" + } + ] + } + } +] +``` + +## Related content + diff --git a/articles/operators/array-query/$elemmatch.md b/articles/operators/array-query/$elemmatch.md new file mode 100644 index 0000000..916cd70 --- /dev/null +++ b/articles/operators/array-query/$elemmatch.md @@ -0,0 +1,187 @@ +--- + title: $elemMatch + titleSuffix: Overview of the $elemMatch operator in DocumentDB + description: The $elemmatch operator returns complete array, qualifying criteria with at least one matching array element. +--- + +# $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": "a57511bb-1ea3-4b26-bf0d-8bf928f2bfa8", + "name": "Wide World Importers", + "location": { + "lat": 68.6378, + "lon": -145.2852 + }, + "staff": { + "totalStaff": { + "fullTime": 1, + "partTime": 5 + } + }, + "sales": { + "totalSales": 23399, + "salesByCategory": [ + { + "categoryName": "Smartphones", + "totalSales": 5231 + }, + { + "categoryName": "Laptops", + "totalSales": 18168 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2023, + "Month": 5, + "Day": 17 + }, + "endDate": { + "Year": 2023, + "Month": 5, + "Day": 25 + } + }, + "discounts": [ + { + "categoryName": "Video Games", + "discountPercentage": 20 + }, + { + "categoryName": "Tablets", + "discountPercentage": 18 + } + ] + } + ], + "tag": [ + "#ShopLocal", + "#FashionStore", + "#SeasonalSale", + "#FreeShipping", + "#MembershipDeals" + ] +} +``` + +### Example 1: Find in an array for specific element among the list of elements + +The example finds 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 + } + ] + } + ] + } +] +``` + +## Related content + diff --git a/articles/operators/array-query/$size.md b/articles/operators/array-query/$size.md new file mode 100644 index 0000000..50903fd --- /dev/null +++ b/articles/operators/array-query/$size.md @@ -0,0 +1,190 @@ +--- +title: $size +titleSuffix: Overview of the $size operator in DocumentDB +description: The $size operator is used to query documents where an array field has a specified number of elements. +type: operators +category: window-operators +--- + +# $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": "a57511bb-1ea3-4b26-bf0d-8bf928f2bfa8", + "name": "Wide World Importers", + "location": { + "lat": 68.6378, + "lon": -145.2852 + }, + "staff": { + "totalStaff": { + "fullTime": 1, + "partTime": 5 + } + }, + "sales": { + "totalSales": 23399, + "salesByCategory": [ + { + "categoryName": "Smartphones", + "totalSales": 5231 + }, + { + "categoryName": "Laptops", + "totalSales": 18168 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2023, + "Month": 5, + "Day": 17 + }, + "endDate": { + "Year": 2023, + "Month": 5, + "Day": 25 + } + }, + "discounts": [ + { + "categoryName": "Video Games", + "discountPercentage": 20 + }, + { + "categoryName": "Tablets", + "discountPercentage": 18 + } + ] + } + ], + "tag": [ + "#ShopLocal", + "#FashionStore", + "#SeasonalSale", + "#FreeShipping", + "#MembershipDeals" + ] +} +``` + +### Example 1: Finding documents with a specific number of elements in an array + +The example 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 + } + ] + } + } +] +``` + +## Related content + diff --git a/articles/operators/array-query/TOC.yml b/articles/operators/array-query/TOC.yml new file mode 100644 index 0000000..75bc515 --- /dev/null +++ b/articles/operators/array-query/TOC.yml @@ -0,0 +1,6 @@ +- name: $all + href: $all.md +- name: $elemMatch + href: $elemmatch.md +- name: $size + href: $size.md \ No newline at end of file