Merge branch 'MicrosoftDocs:main' into main

Author: jesscioffi

articles/cosmos-db/mongodb/TOC.yml

@@ -284,6 +284,20 @@
       href: connect-using-compass.md
     - name: Connect using Robo 3T
       href: connect-using-robomongo.md
+    - name: Develop applications
+      items:
+        - name: JavaScript
+          items: 
+            - name: Get started
+              href: how-to-javascript-get-started.md
+            - name: Manage databases
+              href: how-to-javascript-manage-databases.md
+            - name: Manage collections
+              href: how-to-javascript-manage-collections.md         
+            - name: Manage documents
+              href: how-to-javascript-manage-documents.md         
+            - name: Manage queries
+              href: how-to-javascript-manage-queries.md         
     - name: Connect using Mongoose
       href: connect-using-mongoose.md
     - name: Distribute reads globally

articles/cosmos-db/mongodb/how-to-javascript-get-started.md

@@ -0,0 +1,157 @@
+---
+title: Get started with Azure Cosmos DB MongoDB API and JavaScript
+description: Get started developing a JavaScript application that works with Azure Cosmos DB MongoDB API. This article helps you learn how to set up a project and configure access to an Azure Cosmos DB MongoDB API database.
+author: seesharprun
+ms.author: sidandrews
+ms.service: cosmos-db
+ms.subservice: cosmosdb-mongo
+ms.devlang: javascript
+ms.topic: how-to
+ms.date: 06/23/2022
+ms.custom: devx-track-js
+
+---
+
+# Get started with Azure Cosmos DB MongoDB API and JavaScript
+[!INCLUDE[appliesto-mongo-api](../includes/appliesto-mongodb-api.md)]
+
+This article shows you how to connect to Azure Cosmos DB MongoDB API using the native MongoDB npm package. Once connected, you can perform operations on databases, collections, and docs.
+
+> [!NOTE]
+> The [example code snippets](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples) are available on GitHub as a JavaScript project.
+
+[MongoDB API reference documentation](https://docs.mongodb.com/drivers/node) | [MongoDB Package (npm)](https://www.npmjs.com/package/mongodb)
+
+
+## Prerequisites
+
+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free).
+* [Node.js LTS](https://nodejs.org/en/download/)
+* [Azure Command-Line Interface (CLI)](/cli/azure/) or [Azure PowerShell](/powershell/azure/)
+* [Azure Cosmos DB MongoDB API resource](quickstart-javascript.md#create-an-azure-cosmos-db-account)
+
+## Create a new JavaScript app
+
+1. Create a new JavaScript application in an empty folder using your preferred terminal. Use the [``npm init``](https://docs.npmjs.com/cli/v8/commands/npm-init) command to begin the prompts to create the `package.json` file. Accept the defaults for the prompts. 
+
+    ```console
+    npm init
+    ```
+
+2. Add the [MongoDB](https://www.npmjs.com/package/mongodb) npm package to the JavaScript project. Use the [``npm install package``](https://docs.npmjs.com/cli/v8/commands/npm-install) command specifying the name of the npm package. The `dotenv` package is used to read the environment variables from a `.env` file during local development.
+
+    ```console
+    npm install mongodb dotenv
+    ```
+
+3. To run the app, use a terminal to navigate to the application directory and run the application.
+
+    ```console
+    node index.js
+    ```
+
+## Connect with MongoDB native driver to Azure Cosmos DB MongoDB API
+
+To connect with the MongoDB native driver to Azure Cosmos DB, create an instance of the [``MongoClient``](https://mongodb.github.io/node-mongodb-native/4.5/classes/MongoClient.html#connect) class. This class is the starting point to perform all operations against databases. 
+
+The most common constructor for **MongoClient** has two parameters:
+
+| Parameter | Example value | Description |
+| --- | --- | --- |
+| ``url`` | ``COSMOS_CONNECTION_STRIN`` environment variable | MongoDB API connection string to use for all requests |
+| ``options`` | `{ssl: true, tls: true, }` | [MongoDB Options](https://mongodb.github.io/node-mongodb-native/4.5/interfaces/MongoClientOptions.html) for the connection. |
+
+Refer to the [Troubleshooting guide](error-codes-solutions.md) for connection issues.
+
+## Get resource name
+
+### [Azure CLI](#tab/azure-cli)
+
+[!INCLUDE [Azure CLI - get resource name](<./includes/azure-cli-get-resource-name.md>)]
+
+### [PowerShell](#tab/azure-powershell)
+
+[!INCLUDE [Powershell - set resource name](<./includes/powershell-set-resource-name.md>)]
+
+### [Portal](#tab/azure-portal)
+
+Skip this step and use the information for the portal in the next step.
+
+---
+
+## Retrieve your connection string
+
+### [Azure CLI](#tab/azure-cli)
+
+[!INCLUDE [Azure CLI - get connection string](<./includes/azure-cli-get-connection-string.md>)]
+
+### [PowerShell](#tab/azure-powershell)
+
+[!INCLUDE [Powershell - get connection string](<./includes/powershell-get-connection-string.md>)]
+
+### [Portal](#tab/azure-portal)
+
+> [!TIP]
+> For this guide, we recommend using the resource group name ``msdocs-cosmos``.
+
+[!INCLUDE [Portal - get connection string](<./includes/portal-get-connection-string-from-sign-in.md>)]
+
+---
+
+## Configure environment variables
+
+[!INCLUDE [Multitab - store connection string in environment variable](<./includes/environment-variables-connection-string.md>)]
+
+## Create MongoClient with connection string
+
+
+1. Add dependencies to reference the MongoDB and DotEnv npm packages. 
+
+    :::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/101-client-connection-string/index.js" id="package_dependencies":::
+
+2. Define a new instance of the ``MongoClient,`` class using the constructor, and [``process.env.``](https://nodejs.org/dist/latest-v8.x/docs/api/process.html#process_process_env) to use the connection string.
+
+    :::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/101-client-connection-string/index.js" id="client_credentials":::
+
+For more information on different ways to create a ``MongoClient`` instance, see [MongoDB NodeJS Driver Quick Start](https://www.npmjs.com/package/mongodb#quick-start).
+
+## Close the MongoClient connection
+
+When your application is finished with the connection remember to close it. That `.close()` call should be after all database calls are made. 
+
+```javascript
+client.close()
+```
+
+## Use MongoDB client classes with Cosmos DB for MongoDB API
+
+[!INCLUDE [Conceptual object model](<./includes/conceptual-object-model.md>)]
+
+Each type of resource is represented by one or more associated JavaScript classes. Here's a list of the most common classes:
+
+| Class | Description |
+|---|---|
+|[``MongoClient``](https://mongodb.github.io/node-mongodb-native/4.5/classes/MongoClient.html)|This class provides a client-side logical representation for the MongoDB API layer on Cosmos DB. The client object is used to configure and execute requests against the service.|
+|[``Db``](https://mongodb.github.io/node-mongodb-native/4.5/classes/Db.html)|This class is a reference to a database that may, or may not, exist in the service yet. The database is validated server-side when you attempt to access it or perform an operation against it.|
+|[``Collection``](https://mongodb.github.io/node-mongodb-native/4.5/classes/Collection.html)|This class is a reference to a collection that also may not exist in the service yet. The collection is validated server-side when you attempt to work with it.|
+
+The following guides show you how to use each of these classes to build your application.
+
+**Guide**:
+
+* [Manage databases](how-to-javascript-manage-databases.md)  
+* [Manage collections](how-to-javascript-manage-collections.md) 
+* [Manage documents](how-to-javascript-manage-documents.md) 
+* [Use queries to find documents](how-to-javascript-manage-queries.md) 
+
+## See also
+
+- [Package (NuGet)](https://www.nuget.org/packages/Microsoft.Azure.Cosmos)
+- [API reference](https://docs.mongodb.com/drivers/node)
+
+## Next steps
+
+Now that you've connected to a MongoDB API account, use the next guide to create and manage databases.
+
+> [!div class="nextstepaction"]
+> [Create a database in Azure Cosmos DB MongoDB API using JavaScript](how-to-javascript-manage-databases.md)

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

@@ -0,0 +1,81 @@
+---
+title: Create a collection in Azure Cosmos DB MongoDB API using JavaScript
+description: Learn how to work with a collection in your Azure Cosmos DB MongoDB API database using the JavaScript SDK.
+author: seesharprun
+ms.author: sidandrews
+ms.service: cosmos-db
+ms.subservice: cosmosdb-mongo
+ms.devlang: javascript
+ms.topic: how-to
+ms.date: 06/23/2022
+ms.custom: devx-track-js
+---
+
+# Manage a collection in Azure Cosmos DB MongoDB API using JavaScript
+
+[!INCLUDE[appliesto-mongodb-api](../includes/appliesto-mongodb-api.md)]
+
+Manage your MongoDB collection stored in Cosmos DB with the native MongoDB client driver.
+
+> [!NOTE]
+> The [example code snippets](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples) are available on GitHub as a JavaScript project.
+
+[MongoDB API reference documentation](https://docs.mongodb.com/drivers/node) | [MongoDB Package (npm)](https://www.npmjs.com/package/mongodb)
+
+
+## Name a collection
+
+In Azure Cosmos DB, a collection is analogous to a table in a relational database. When you create a collection, the collection name forms a segment of the URI used to access the collection resource and any child docs.
+
+Here are some quick rules when naming a collection:
+
+* Keep collection names between 3 and 63 characters long
+* Collection names can only contain lowercase letters, numbers, or the dash (-) character.
+* Container names must start with a lowercase letter or number.
+
+## Get collection instance
+
+Use an instance of the **Collection** class to access the collection on the server.
+
+* [MongoClient.Db.Collection](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html)
+
+The following code snippets assume you've already created your [client connection](how-to-javascript-get-started.md#create-mongoclient-with-connection-string) and that you [close your client connection](how-to-javascript-get-started.md#close-the-mongoclient-connection) after these code snippets.
+
+## Create a collection
+
+To create a collection, insert a document into the collection.
+
+* [MongoClient.Db.Collection](https://mongodb.github.io/node-mongodb-native/4.5/classes/Db.html#collection)
+* [MongoClient.Db.Collection.insertOne](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html#insertOne)
+* [MongoClient.Db.Collection.insertMany](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html#insertMany)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/203-insert-doc/index.js" id="database_object":::
+
+## Drop a collection
+
+* [MongoClient.Db.dropCollection](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html#dropCollection)
+
+Drop the collection from the database to remove it permanently. However, the next insert or update operation that accesses the collection will create a new collection with that name.
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/299-drop-collection/index.js" id="drop_collection":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/299-drop-collection/index.js" id="console_result":::
+
+## Get collection indexes
+
+An index is used by the MongoDB query engine to improve performance to database queries.
+
+* [MongoClient.Db.Collection.indexes](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html#indexes)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/225-get-collection-indexes/index.js" id="collection":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/225-get-collection-indexes/index.js" id="console_result":::
+
+## See also
+
+- [Get started with Azure Cosmos DB MongoDB API and JavaScript](how-to-javascript-get-started.md)
+- [Create a database](how-to-javascript-manage-databases.md)

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

@@ -0,0 +1,117 @@
+---
+title: Manage a MongoDB database using JavaScript
+description: Learn how to manage your Cosmos DB resource when it provides the MongoDB API with a JavaScript SDK.
+author: seesharprun
+ms.author: sidandrews
+ms.service: cosmos-db
+ms.subservice: cosmosdb-mongo
+ms.devlang: javascript
+ms.topic: how-to
+ms.date: 06/23/2022
+ms.custom: devx-track-js
+---
+
+# Manage a MongoDB database using JavaScript
+
+[!INCLUDE[appliesto-mongodb-api](../includes/appliesto-mongodb-api.md)]
+
+Your MongoDB server in Azure Cosmos DB is available from the common npm packages for MongoDB such as:
+
+* [MongoDB](https://www.npmjs.com/package/mongodb)
+
+> [!NOTE]
+> The [example code snippets](https://github.com/Azure-Samples/cosmos-db-mongodb-api-javascript-samples) are available on GitHub as a JavaScript project.
+
+[MongoDB API reference documentation](https://docs.mongodb.com/drivers/node) | [MongoDB Package (npm)](https://www.npmjs.com/package/mongodb)
+
+## Name a database
+
+In Azure Cosmos DB, a database is analogous to a namespace. When you create a database, the database name forms a segment of the URI used to access the database resource and any child resources.
+
+Here are some quick rules when naming a database:
+
+* Keep database names between 3 and 63 characters long
+* Database names can only contain lowercase letters, numbers, or the dash (-) character.
+* Database names must start with a lowercase letter or number.
+
+Once created, the URI for a database is in this format:
+
+``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>``
+
+## Get database instance
+
+The database holds the collections and their documents. Use an instance of the **Db** class to access the databases on the server.
+
+* [MongoClient.Db](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html)
+
+The following code snippets assume you've already created your [client connection](how-to-javascript-get-started.md#create-mongoclient-with-connection-string) and that you [close your client connection](how-to-javascript-get-started.md#close-the-mongoclient-connection) after these code snippets.
+
+## Get server information
+
+Access the **Admin** class to retrieve server information. You don't need to specify the database name in the `db` method. The information returned is specific to MongoDB and doesn't represent the Azure Cosmos DB platform itself.
+
+* [MongoClient.Db.Admin](https://mongodb.github.io/node-mongodb-native/4.7/classes/Admin.html)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/200-admin/index.js" id="server_info":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/200-admin/index.js" id="console_result":::
+
+## Does database exist?
+
+The native MongoDB driver for JavaScript creates the database if it doesn't exist when you access it. If you would prefer to know if the database already exists before using it, get the list of current databases and filter for the name:
+
+* [MongoClient.Db.Admin.listDatabases](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/201-does-database-exist/index.js" id="does_database_exist":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/201-does-database-exist/index.js" id="console_result":::
+
+## Get list of databases, collections, and document count
+
+When you manage your MongoDB server programmatically, it's helpful to know what databases and collections are on the server and how many documents in each collection.
+
+* [MongoClient.Db.Admin.listDatabases](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html)
+* [MongoClient.Db.listCollections](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html#listCollections)
+* [MongoClient.Db.Collection](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html)
+* [MongoClient.Db.Collection.countDocuments](https://mongodb.github.io/node-mongodb-native/4.7/classes/Collection.html#countDocuments)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/202-get-doc-count/index.js" id="database_object":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/202-get-doc-count/index.js" id="console_result":::
+
+## Get database object instance
+
+To get a database object instance, call the following method. This method accepts an optional database name and can be part of a chain.
+
+* [``MongoClient.Db``](https://mongodb.github.io/node-mongodb-native/4.5/classes/Db.html)
+
+A database is created when it is accessed. The most common way to access a new database is to add a document to a collection. In one line of code using chained objects, the database, collection, and doc are created.
+
+```javascript
+const insertOneResult = await client.db("adventureworks").collection("products").insertOne(doc);
+```
+
+Learn more about working with [collections](how-to-javascript-manage-collections.md) and documents.
+
+## Drop a database
+
+A database is removed from the server using the dropDatabase method on the DB class. 
+
+* [DB.dropDatabase](https://mongodb.github.io/node-mongodb-native/4.7/classes/Db.html#dropDatabase)
+
+:::code language="javascript" source="~/samples-cosmosdb-mongodb-javascript/300-drop-database/index.js" id="drop_database":::
+
+The preceding code snippet displays the following example console output:
+
+:::code language="console" source="~/samples-cosmosdb-mongodb-javascript/300-drop-database/index.js" id="console_result":::
+
+## See also
+
+- [Get started with Azure Cosmos DB MongoDB API and JavaScript](how-to-javascript-get-started.md)
+- Work with a collection](how-to-javascript-manage-collections.md)