Merge pull request #224969 from gahl-levy/mongo-basics-docs

New docs for Mongo basics

Author: v-dirichards

articles/cosmos-db/mongodb/TOC.yml

@@ -58,6 +58,14 @@
       href: tutorial-query.md
     - name: 3 - Distribute data globally
       href: tutorial-global-distribution.md
+    - name: Aggregation pipeline
+      href: tutorial-aggregation.md
+    - name: Inserting data
+      href: tutorial-insert.md
+    - name: Updating data
+      href: tutorial-update.md
+    - name: Deleting data
+      href: tutorial-delete.md
     - name: Create Jupyter notebooks
       href: ../nosql/tutorial-create-notebook.md
 - name: Samples

articles/cosmos-db/mongodb/tutorial-aggregation.md

@@ -0,0 +1,111 @@
+---
+title: Getting Started with Aggregation Pipeline
+description: Learn how to get started with Cosmos DB for MongoDB aggregation pipeline for advanced data analysis and manipulation.
+author: gahl-levy
+ms.author: gahllevy
+ms.service: cosmos-db
+ms.subservice: mongodb
+ms.topic: tutorial
+ms.date: 01/24/2023
+ms.reviewer: mjbrown
+---
+
+# Getting Started with Aggregation Pipeline
+
+The aggregation pipeline is a powerful tool that allows developers to perform advanced data analysis and manipulation on their collections. The pipeline is a sequence of data processing operations, which are performed on the input documents to produce a computed output. The pipeline stages process the input documents and pass the result to the next stage. Each stage performs a specific operation on the data, such as filtering, grouping, sorting, and transforming.
+
+## Basic Syntax
+
+The basic syntax for an aggregation pipeline is as follows:
+
+```javascript
+db.collection.aggregate([    { stage1 },    { stage2 },    ...    { stageN }])
+```
+
+Where db.collection is the MongoDB collection you want to perform the aggregation on, and stage1, stage2, ..., stageN are the pipeline stages you want to apply.
+
+## Sample Stages
+
+Cosmos DB for MongoDB provides a wide range of stages that you can use in your pipeline, including:
+
+* $match: Filters the documents to pass only the documents that match the specified condition.
+* $project: Transforms the documents to a new form by adding, removing, or updating fields.
+* $group: Groups documents by one or more fields and performs various aggregate functions on the grouped data.
+* $sort: Sorts the documents based on the specified fields.
+* $skip: Skips the specified number of documents.
+* $limit: Limits the number of documents passed to the next stage.
+* $unwind: Deconstructs an array field from the input documents to output a document for each element.
+
+To view all available stages, see [supported features](feature-support-42.md)
+
+## Examples
+
+Here are some examples of how you can use the aggregation pipeline to perform various operations on your data:
+
+Filtering: To filter documents that have a "quantity" field greater than 20, you can use the following pipeline:
+```javascript
+db.collection.aggregate([
+    { $match: { quantity: { $gt: 20 } } }
+])
+```
+
+Grouping: To group documents by the "category" field and calculate the total "quantity" for each group, you can use the following pipeline:
+```javascript
+db.collection.aggregate([
+    { $group: { _id: "$category", totalQuantity: { $sum: "$quantity" } } }
+])
+```
+
+Sorting: To sort documents by the "price" field in descending order, you can use the following pipeline:
+```javascript
+db.collection.aggregate([
+    { $sort: { price: -1 } }
+])
+```
+
+Transforming: To add a new field "discount" to documents that have a "price" greater than 100, you can use the following pipeline:
+
+```javascript
+db.collection.aggregate([
+    { $project: { item: 1, price: 1, discount: { $cond: [{ $gt: ["$price", 100] }, 10, 0 ] } } }
+])
+```
+
+Unwinding: To separate all the subdocuments from the array field 'tags' and create a new document for each value, you can use the following pipeline:
+```javascript
+db.collection.aggregate([
+    { $unwind: "$tags" }
+])
+```
+
+## Example with multiple stages
+
+```javascript
+db.sales.aggregate([
+  { $match: { date: { $gte: "2021-01-01", $lt: "2021-03-01" } } },
+  { $group: { _id: "$category", totalSales: { $sum: "$sales" } } },
+  { $sort: { totalSales: -1 } },
+  { $limit: 5 }
+])
+```
+
+In this example, we are using a sample collection called "sales" which has documents with the following fields: "date", "category", and "sales".
+
+The first stage { $match: { date: { $gte: "2021-01-01", $lt: "2021-03-01" } } } filters the documents by the "date" field, only passing documents with a date between January 1st, 2021 and February 28th, 2021. We are using a string date format with the format "YYYY-MM-DD".
+
+The second stage { $group: { _id: "$category", totalSales: { $sum: "$sales" } } } groups the documents by the "category" field and calculates the total sales for each group.
+
+The third stage { $sort: { totalSales: -1 } } sorts the documents by the "totalSales" field in descending order.
+
+The fourth stage { $limit: 5 } limits the number of documents passed to the next stage to only the top 5.
+
+As a result, the pipeline will return the top 5 categories by total sales for the specified date range.
+
+## Next steps
+
+- Learn how to [use Studio 3T](connect-using-mongochef.md) with Azure Cosmos DB for MongoDB.
+- Learn how to [use Robo 3T](connect-using-robomongo.md) with Azure Cosmos DB for MongoDB.
+- Explore MongoDB [samples](nodejs-console-app.md) with Azure Cosmos DB for MongoDB.
+- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
+  - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).
+  - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md).

articles/cosmos-db/mongodb/tutorial-delete.md

@@ -0,0 +1,54 @@
+---
+title: Deleting Data into Cosmos DB for MongoDB
+description: Learn how to get started with deleting data in Cosmos DB for MongoDB.
+author: gahl-levy
+ms.author: gahllevy
+ms.service: cosmos-db
+ms.subservice: mongodb
+ms.topic: tutorial
+ms.date: 01/24/2023
+ms.reviewer: mjbrown
+---
+
+# Deleting Data into Cosmos DB for MongoDB
+
+One of the most basic operations is deleting data in a collection. In this guide, we will cover everything you need to know about deleting data using the Mongo Shell (Mongosh).
+
+## Understanding the deleteOne() and deleteMany() Methods
+
+The most common way to delete data in MongoDB is to delete individual documents from a collection. You can do this using the deleteOne() or deleteMany() method.
+
+The deleteOne() method is used to delete a single document from a collection that matches a specific filter. For example, if you wanted to delete a user with the name "John Doe" from the "users" collection, you would use the following command:
+
+```javascript
+db.users.deleteOne({ "name": "John Doe" })
+```
+
+The deleteMany() method, on the other hand, is used to delete multiple documents from a collection that match a specific filter. For example, if you wanted to delete all users with an age less than 30 from the "users" collection, you would use the following command:
+
+```javascript
+db.users.deleteMany({ "age": { $lt: 30 } })
+```
+
+It's important to note that both of these methods return an object with the following properties:
+
+deletedCount: The number of documents deleted.
+acknowledged: This property will be true.
+
+## Deleting a Collection
+
+To delete an entire collection, use the drop() method. For example, if you wanted to delete the "users" collection, you would use the following command:
+
+```javascript
+db.users.drop()
+This will delete the "users" collection and all of its documents permanently.
+```
+
+## Next steps
+
+- Learn how to [use Studio 3T](connect-using-mongochef.md) with Azure Cosmos DB for MongoDB.
+- Learn how to [use Robo 3T](connect-using-robomongo.md) with Azure Cosmos DB for MongoDB.
+- Explore MongoDB [samples](nodejs-console-app.md) with Azure Cosmos DB for MongoDB.
+- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
+  - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).
+  - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md).

articles/cosmos-db/mongodb/tutorial-insert.md

@@ -0,0 +1,65 @@
+---
+title: Getting Started with Inserting data into Cosmos DB for MongoDB
+description: Learn how to get started with inserting data into Cosmos DB for MongoDB.
+author: gahl-levy
+ms.author: gahllevy
+ms.service: cosmos-db
+ms.subservice: mongodb
+ms.topic: tutorial
+ms.date: 01/24/2023
+ms.reviewer: mjbrown
+---
+
+# Inserting Data into Cosmos DB for MongoDB
+One of the most basic operations is inserting data into a collection. In this guide, we will cover everything you need to know about inserting data using the Mongo Shell (Mongosh).
+
+## Inserting a Single Document
+
+The most basic way to insert data into MongoDB is to insert a single document. To do this, you can use the db.collection.insertOne() method. The insertOne() method takes a single document as its argument and inserts it into the specified collection. Here's an example of how you might use this method:
+
+```javascript
+db.myCollection.insertOne({
+  name: "John Smith",
+  age: 30,
+  address: "123 Main St"
+});
+```
+
+In this example, we're inserting a document into the "myCollection" collection with the following fields: "name", "age", and "address". Once the command is executed, you will see the acknowledged: true and insertedId: ObjectId("5f5d5f5f5f5f5f5f5f5f5f5f") in the output, where the insertedId is the unique identifier generated by MongoDB for the inserted document.
+
+## Inserting Multiple Documents
+
+In many cases, you'll need to insert multiple documents at once. To do this, you can use the db.collection.insertMany() method. The insertMany() method takes an array of documents as its argument and inserts them into the specified collection. Here's an example:
+
+```javascript
+db.myCollection.insertMany([
+  {name: "Jane Doe", age: 25, address: "456 Park Ave"},
+  {name: "Bob Smith", age: 35, address: "789 Elm St"},
+  {name: "Sally Johnson", age: 40, address: "111 Oak St"}
+]);
+```
+
+In this example, we're inserting three documents into the "myCollection" collection. Each document has the same fields as the previous example: "name", "age", and "address". The insertMany() method returns an acknowledged: true and insertedIds: [ObjectId("5f5d5f5f5f5f5f5f5f5f5f5f"), ObjectId("5f5d5f5f5f5f5f5f5f5f5f5f"), ObjectId("5f5d5f5f5f5f5f5f5f5f5f5f")] where insertedIds is an array of unique identifiers generated by MongoDB for each inserted document.
+
+## Inserting with Options
+
+Both insertOne() and insertMany() accept an optional second argument, which can be used to specify options for the insert operation. For example, to set the "ordered" option to false, you can use the following code:
+
+```javascript
+db.myCollection.insertMany([
+  {name: "Jane Doe", age: 25, address: "456 Park Ave"},
+  {name: "Bob Smith", age: 35, address: "789 Elm St"},
+  {name: "Sally Johnson", age: 40, address: "111 Oak St"}
+], {ordered: false});
+```
+
+This tells MongoDB to insert the documents in an unordered fashion, meaning that if one document fails to be inserted, it will continue with the next one. This is recommended for write performance in Cosmos DB for MongoDB
+
+## Next steps
+
+- Learn how to [use Studio 3T](connect-using-mongochef.md) with Azure Cosmos DB for MongoDB.
+- Learn how to [use Robo 3T](connect-using-robomongo.md) with Azure Cosmos DB for MongoDB.
+- Explore MongoDB [samples](nodejs-console-app.md) with Azure Cosmos DB for MongoDB.
+- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
+  - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).
+  - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md).

articles/cosmos-db/mongodb/tutorial-update.md

@@ -0,0 +1,79 @@
+---
+title: Updating Data into Cosmos DB for MongoDB
+description: Learn how to get started with updating data in Cosmos DB for MongoDB.
+author: gahl-levy
+ms.author: gahllevy
+ms.service: cosmos-db
+ms.subservice: mongodb
+ms.topic: tutorial
+ms.date: 01/24/2023
+ms.reviewer: mjbrown
+---
+
+# Updating Data into Cosmos DB for MongoDB
+
+One of the most basic operations is updating data into a collection. In this guide, we will cover everything you need to know about updating data using the Mongo Shell (Mongosh).
+
+## Using updateOne() Method
+
+The updateOne() method updates the first document that matches a specified filter. The method takes two parameters:
+
+filter: A document that specifies the criteria for the update. The filter is used to match the documents in the collection that should be updated. The filter document must be a valid query document.
+
+update: A document that specifies the update operations to perform on the matching documents. The update document must be a valid update document.
+
+```javascript
+db.collection.updateOne(
+   <filter>,
+   <update>
+)
+```
+
+For example, to update the name of a customer with _id equal to 1, you can use the following command:
+
+```javascript
+db.customers.updateOne(
+   { _id: 1 },
+   { $set: { name: "Jane Smith" } }
+)
+```
+
+In the above example, db.customers is the collection name, { _id: 1 } is the filter which matches the first document that has _id equal to 1 and { $set: { name: "Jane Smith" } } is the update operation which sets the name field of the matched document to "Jane Smith".
+
+You can also use other update operators like $inc, $mul, $rename, $unset etc. to update the data.
+
+## updateMany() Method
+
+The updateMany() method updates all documents that match a specified filter. The method takes two parameters:
+
+filter: A document that specifies the criteria for the update. The filter is used to match the documents in the collection that should be updated. The filter document must be a valid query document.
+update: A document that specifies the update operations to perform on the matching documents. The update document must be a valid update document.
+
+```javascript
+db.collection.updateMany(
+   <filter>,
+   <update>
+)
+```
+
+For example, to update the name of all customers that live in "New York", you can use the following command:
+
+```javascript
+db.customers.updateMany(
+   { city: "New York" },
+   { $set: { name: "Jane Smith" } }
+)
+```
+
+In the above example, db.customers is the collection name, { city: "New York" } is the filter which matches all the documents that have city field equal to "New York" and { $set: { name: "Jane Smith" } } is the update operation which sets the name field of all the matched documents to "Jane Smith".
+
+You can also use other update operators like $inc, $mul, $rename, $unset, etc. to update the data.
+
+## Next steps
+
+- Learn how to [use Studio 3T](connect-using-mongochef.md) with Azure Cosmos DB for MongoDB.
+- Learn how to [use Robo 3T](connect-using-robomongo.md) with Azure Cosmos DB for MongoDB.
+- Explore MongoDB [samples](nodejs-console-app.md) with Azure Cosmos DB for MongoDB.
+- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
+  - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).
+  - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md).