Merge pull request #109772 from LuisBosquez/master

Mongo extension commands and Mongoose article

Author: PMEds28

articles/cosmos-db/media/mongodb-mongoose/db-level-throughput.png

@@ -10,13 +10,13 @@ ms.author: sngun
 
 # Use MongoDB extension commands to manage data stored in Azure Cosmos DB’s API for MongoDB 
 
-Azure Cosmos DB is Microsoft's globally distributed multi-model database service. You can communicate with the Azure Cosmos DB’s API for MongoDB by using any of the open source [MongoDB client drivers](https://docs.mongodb.org/ecosystem/drivers). The Azure Cosmos DB’s API for MongoDB enables the use of existing client drivers by adhering to the [MongoDB wire protocol](https://docs.mongodb.org/manual/reference/mongodb-wire-protocol).
+Azure Cosmos DB is Microsoft's globally distributed multi-model database service. You can communicate with the Azure Cosmos DB’s API for MongoDB by using any of the open-source [MongoDB client drivers](https://docs.mongodb.org/ecosystem/drivers). The Azure Cosmos DB’s API for MongoDB enables the use of existing client drivers by adhering to the [MongoDB wire protocol](https://docs.mongodb.org/manual/reference/mongodb-wire-protocol).
 
 By using the Azure Cosmos DB’s API for MongoDB, you can enjoy the benefits Cosmos DB such as global distribution, automatic sharding, high availability, latency guarantees, automatic, encryption at rest, backups, and many more, while preserving your investments in your MongoDB app.
 
 ## MongoDB protocol support
 
-By default, the Azure Cosmos DB’s API for MongoDB is compatible with MongoDB server version 3.2, for more details, see [supported features and syntax](mongodb-feature-support.md). The features or query operators added in MongoDB version 3.4 are currently available as a preview in the Azure Cosmos DB’s API for MongoDB. The following extension commands support Azure Cosmos DB specific functionality when performing CRUD operations on the data stored in Azure Cosmos DB’s API for MongoDB:
+By default, the Azure Cosmos DB’s API for MongoDB is compatible with MongoDB server version 3.2, for more details, see [supported features and syntax](mongodb-feature-support.md). The features or query operators added in MongoDB version 3.4 are currently available as a preview in the Azure Cosmos DB’s API for MongoDB. The following extension commands support specific Azure Cosmos DB functionality when performing CRUD operations on the data stored in Azure Cosmos DB’s API for MongoDB:
 
 * [Create database](#create-database)
 * [Update database](#update-database)
@@ -155,12 +155,12 @@ The create collection extension command creates a new MongoDB collection. The da
 
 The following table describes the parameters within the command:
 
-|**Field**|**Type** |**Description** |
-|---------|---------|---------|
-| customAction    | string | Name of the custom command. Must be "CreateCollection"     |
-| collection      | string | Name of the collection                                   |
-| offerThroughput | int    | Provisioned Throughput to set on the database. It's an Optional parameter |
-| shardKey        | string | Shard Key path to create a sharded collection. It's an Optional parameter |
+| **Field** | **Type** | **Required** | **Description** |
+|---------|---------|---------|---------|
+| customAction | string | Required | Name of the custom command. Must be "CreateCollection".|
+| collection | string | Required | Name of the collection. No special characters are allowed.|
+| offerThroughput | int | Optional* | Provisioned throughput to set on the database. If this parameter is not provided, it will default to the minimum, 400 RU/s. * To specify throughput beyond 10,000 RU/s, the `shardKey` parameter is required.|
+| shardKey | string | Optional* | The path to the Shard Key for the sharded collection. This parameter is required if you set more than 10,000 RU/s in `offerThroughput`.  If it is specified, all documents inserted will require this value. |
 
 ### Output
 
@@ -179,7 +179,7 @@ db.runCommand({customAction: "CreateCollection", collection: "testCollection", o
 
 **Create a sharded collection**
 
-To create a sharded collection with name "testCollection" and provisioned throughput of 1000 RUs, use the following command:
+To create a sharded collection with name "testCollection" and provisioned throughput of 1000 RUs, and a shardkey property "a.b", use the following command:
 
 ```shell
 use test

articles/cosmos-db/mongodb-custom-commands.md

@@ -30,6 +30,16 @@ Let's create a Cosmos account. If you already have an account you want to use, y
 
 [!INCLUDE [cosmos-db-create-dbaccount-mongodb](../../includes/cosmos-db-create-dbaccount-mongodb.md)]
 
+### Create a database 
+In this application we will cover two ways of creating collections in Azure Cosmos DB: 
+- **Storing each object model in a separate collection**: We recommend [creating a database with dedicated throughput](set-throughput.md#set-throughput-on-a-database). Using this capacity model will give you better cost efficiency.
+
+    :::image type="content" source="./media/mongodb-mongoose/db-level-throughput.png" alt-text="Node.js tutorial - Screenshot of the Azure portal, showing how to create a database in the Data Explorer for an Azure Cosmos DB account, for use with the Mongoose Node module":::
+
+- **Storing all object models in a single Cosmos DB collection**: If you'd prefer to store all models in a single collection, you can just create a new database without selecting the Provision Throughput option. Using this capacity model will create each collection with its own throughput capacity for every object model.
+
+After you create the database, you'll use the name in the `COSMOSDB_DBNAME` environment variable below.
+
 ## Set up your Node.js application
 
 >[!Note]
@@ -41,8 +51,8 @@ Let's create a Cosmos account. If you already have an account you want to use, y
 
     Answer the questions and your project will be ready to go.
 
-1. Add a new file to the folder and name it ```index.js```.
-1. Install the necessary packages using one of the ```npm install``` options:
+2. Add a new file to the folder and name it ```index.js```.
+3. Install the necessary packages using one of the ```npm install``` options:
    * Mongoose: ```npm install mongoose@5 --save```
 
      > [!Note]
@@ -53,26 +63,26 @@ Let's create a Cosmos account. If you already have an account you want to use, y
      >[!Note]
      > The ```--save``` flag adds the dependency to the package.json file.
 
-1. Import the dependencies in your index.js file.
+4. Import the dependencies in your index.js file.
 
     ```JavaScript
    var mongoose = require('mongoose');
    var env = require('dotenv').config();   //Use the .env file to load the variables
     ```
 
-1. Add your Cosmos DB connection string and Cosmos DB Name to the ```.env``` file. Replace the placeholders {cosmos-account-name} and {dbname} with your own Cosmos account name and database name, without the brace symbols.
+5. Add your Cosmos DB connection string and Cosmos DB Name to the ```.env``` file. Replace the placeholders {cosmos-account-name} and {dbname} with your own Cosmos account name and database name, without the brace symbols.
 
     ```JavaScript
    # You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos account.
 
-   COSMODDB_USER = "<Azure Cosmos account's user name>"
-   COSMOSDB_PASSWORD = "<Azure Cosmos account passowrd>"
+   COSMODDB_USER = "<Azure Cosmos account's user name, usually the database account name>"
+   COSMOSDB_PASSWORD = "<Azure Cosmos account password, this is one of the keys specified in your account>"
    COSMOSDB_DBNAME = "<Azure Cosmos database name>"
    COSMOSDB_HOST= "<Azure Cosmos Host name>"
    COSMOSDB_PORT=10255
     ```
 
-1. Connect to Cosmos DB using the Mongoose framework by adding the following code to the end of index.js.
+6. Connect to Cosmos DB using the Mongoose framework by adding the following code to the end of index.js.
     ```JavaScript
    mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true&replicaSet=globaldb", {
       auth: {
@@ -88,19 +98,15 @@ Let's create a Cosmos account. If you already have an account you want to use, y
 
     Once you are connected to Azure Cosmos DB, you can now start setting up object models in Mongoose.
 
-## Caveats to using Mongoose with Cosmos DB
-
-For every model you create, Mongoose creates a new collection. However, given the per-collection billing model of Cosmos DB, it might not be the most cost-efficient way to go, if you've got multiple object models that are sparsely populated.
-
-This walkthrough covers both models. We'll first cover the walkthrough on storing one type of data per collection. This is the defacto behavior for Mongoose.
+## Best practices for using Mongoose with Cosmos DB
 
-Mongoose also has a concept called [Discriminators](https://mongoosejs.com/docs/discriminators.html). Discriminators are a schema inheritance mechanism. They enable you to have multiple models with overlapping schemas on top of the same underlying MongoDB collection.
+For every model you create, Mongoose creates a new collection. This is best addressed using the [Database Level Throughput option](set-throughput.md#set-throughput-on-a-database), which was previously discussed. To use  a single collection, you need to use Mongoose [Discriminators](https://mongoosejs.com/docs/discriminators.html). Discriminators are a schema inheritance mechanism. They enable you to have multiple models with overlapping schemas on top of the same underlying MongoDB collection.
 
-You can store the various data models in the same collection and then use a filter clause at query time to pull down only the data needed.
+You can store the various data models in the same collection and then use a filter clause at query time to pull down only the data needed. Let's walk through each of the models.
 
 ### One collection per object model
 
-The default Mongoose behavior is to create a MongoDB collection every time you create an Object model. This section explores how to achieve this with Azure Cosmos DB's API for MongoDB. This method is recommended when you have object models with large amounts of data. This is the default operating model for Mongoose, so, you might be familiar with this, if you're familiar with Mongoose.
+This section explores how to achieve this with Azure Cosmos DB's API for MongoDB. This method is our recommended approach since it allows you to control cost and capacity. As a result, the amount of Request Units on the database does not depend on the number of object models. This is the default operating model for Mongoose, so, you might be familiar with this.
 
 1. Open your ```index.js``` again.
 
@@ -313,3 +319,4 @@ As you can see, it is easy to work with Mongoose discriminators. So, if you have
 
 [alldata]: ./media/mongodb-mongoose/mongo-collections-alldata.png
 [multiple-coll]: ./media/mongodb-mongoose/mongo-mutliple-collections.png
+[dbleveltp]: ./media/mongodb-mongoose/db-level-throughput.png