Skip to content

Commit 56efd5b

Browse files
19BMG0019BMG00
authored
Merge pull request #206464 from diberry/diberry/0729-cosmosdb-aggregation
Cosmos DB - MongoDB - JS - Aggregation pipelines
2 parents 827f28e + 1222920 commit 56efd5b

File tree

1 file changed

+128
-3
lines changed

1 file changed

+128
-3
lines changed

‎articles/cosmos-db/mongodb/how-to-javascript-manage-queries.md

Lines changed: 128 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,15 @@ ms.service: cosmos-db
77
ms.subservice: cosmosdb-mongo
88
ms.devlang: javascript
99
ms.topic: how-to
10-
ms.date: 06/23/2022
10+
ms.date: 07/29/2022
1111
ms.custom: devx-track-js
1212
---
1313

14-
# Use a query in Azure Cosmos DB MongoDB API using JavaScript
14+
# Query data in Azure Cosmos DB MongoDB API using JavaScript
1515

1616
[!INCLUDE[appliesto-mongodb-api](../includes/appliesto-mongodb-api.md)]
1717

18-
Use queries to find documents in a collection.
18+
Use [queries](#query-for-documents) and [aggregation pipelines](#aggregation-pipelines) to find and manipulate documents in a collection.
1919

2020
> [!NOTE]
2121
> The [example code snippets](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples) are available on GitHub as a JavaScript project.
@@ -37,6 +37,131 @@ The preceding code snippet displays the following example console output:
3737

3838
:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/275-find/index.js" id="console_result_findone":::
3939

40+
## Aggregation pipelines
41+
42+
Aggregation pipelines are useful to isolate expensive query computation, transformations, and other processing on your Cosmos DB server, instead of performing these operations on the client.
43+
44+
For specific **aggregation pipeline support**, refer to the following:
45+
46+
* [Version 4.2](feature-support-42.md#aggregation-pipeline)
47+
* [Version 4.0](feature-support-40.md#aggregation-pipeline)
48+
* [Version 3.6](feature-support-36.md#aggregation-pipeline)
49+
* [Version 3.2](feature-support-32.md#aggregation-pipeline)
50+
51+
### Aggregation pipeline syntax
52+
53+
A pipeline is an array with a series of stages as JSON objects.
54+
55+
```javascript
56+
const pipeline = [
57+
stage1,
58+
stage2
59+
]
60+
```
61+
62+
### Pipeline stage syntax
63+
64+
A _stage_ defines the operation and the data it's applied to, such as:
65+
66+
* $match - find documents
67+
* $addFields - add field to cursor, usually from previous stage
68+
* $limit - limit the number of results returned in cursor
69+
* $project - pass along new or existing fields, can be computed fields
70+
* $group - group results by a field or fields in pipeline
71+
* $sort - sort results
72+
73+
```javascript
74+
// reduce collection to relative documents
75+
const matchStage = {
76+
'$match': {
77+
'categoryName': { $regex: 'Bikes' },
78+
}
79+
}
80+
81+
// sort documents on field `name`
82+
const sortStage = {
83+
'$sort': {
84+
"name": 1
85+
}
86+
},
87+
```
88+
89+
### Aggregate the pipeline to get iterable cursor
90+
91+
The pipeline is aggregated to produce an iterable cursor.
92+
93+
```javascript
94+
const db = 'adventureworks';
95+
const collection = 'products';
96+
97+
const aggCursor = client.db(databaseName).collection(collectionName).aggregate(pipeline);
98+
99+
await aggCursor.forEach(product => {
100+
console.log(JSON.stringify(product));
101+
});
102+
```
103+
104+
## Use an aggregation pipeline in JavaScript
105+
106+
Use a pipeline to keep data processing on the server before returning to the client.
107+
108+
### Example product data
109+
110+
The aggregations below use the [sample products collection](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples/blob/main/252-insert-many/products.json) with data in the shape of:
111+
112+
```json
113+
[
114+
{
115+
"_id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
116+
"categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
117+
"categoryName": "Bikes, Touring Bikes",
118+
"sku": "BK-T79U-50",
119+
"name": "Touring-1000 Blue, 50",
120+
"description": "The product called \"Touring-1000 Blue, 50\"",
121+
"price": 2384.0700000000002,
122+
"tags": [
123+
]
124+
},
125+
{
126+
"_id": "0F124781-C991-48A9-ACF2-249771D44029",
127+
"categoryId": "56400CF3-446D-4C3F-B9B2-68286DA3BB99",
128+
"categoryName": "Bikes, Mountain Bikes",
129+
"sku": "BK-M68B-42",
130+
"name": "Mountain-200 Black, 42",
131+
"description": "The product called \"Mountain-200 Black, 42\"",
132+
"price": 2294.9899999999998,
133+
"tags": [
134+
]
135+
},
136+
{
137+
"_id": "3FE1A99E-DE14-4D11-B635-F5D39258A0B9",
138+
"categoryId": "26C74104-40BC-4541-8EF5-9892F7F03D72",
139+
"categoryName": "Components, Saddles",
140+
"sku": "SE-T924",
141+
"name": "HL Touring Seat/Saddle",
142+
"description": "The product called \"HL Touring Seat/Saddle\"",
143+
"price": 52.640000000000001,
144+
"tags": [
145+
]
146+
},
147+
]
148+
```
149+
150+
### Example 1: Product subcategories, count of products, and average price
151+
152+
Use the following [sample code](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples/blob/main/280-aggregation/average-price-in-each-product-subcategory.js) to report on average price in each product subcategory.
153+
154+
:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/280-aggregation/average-price-in-each-product-subcategory.js" id="aggregation_1" highlight="26, 43, 53, 56, 66":::
155+
156+
157+
### Example 2: Bike types with price range
158+
159+
Use the following [sample code](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples/blob/main/280-aggregation/bike-types-and-price-ranges.js) to report on the `Bikes` subcategory.
160+
161+
:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/280-aggregation/bike-types-and-price-ranges.js" id="aggregation_1" highlight="23, 30, 38, 45, 68, 80, 85, 98":::
162+
163+
164+
40165
## See also
41166

42167
- [Get started with Azure Cosmos DB MongoDB API and JavaScript](how-to-javascript-get-started.md)

0 commit comments

Comments
 (0)