{"id":695,"date":"2020-03-19T09:00:39","date_gmt":"2020-03-19T16:00:39","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=695"},"modified":"2022-09-20T10:38:14","modified_gmt":"2022-09-20T17:38:14","slug":"preview-native-mongo-shell","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/preview-native-mongo-shell\/","title":{"rendered":"Native Mongo shell on Azure Cosmos DB API for MongoDB now in preview"},"content":{"rendered":"

We are happy to announce the preview release for native Mongo shell v3.6.8 on the Data Explorer for Azure Cosmos DB\u2019s API for MongoDB!<\/p>\n

This will provide you with the native Mongo shell capabilities for database management and CRUD operations. This is available in your Data Explorer either in the Azure Portal<\/a> or in its stand-alone version<\/a>. Check the highlighted note in this article<\/a> to know which Azure Regions are supported today.<\/p>\n

What is the Azure Cosmos DB API for MongoDB?<\/h3>\n

If you haven\u2019t used this API before, this is our implementation of the Wire Protocol defined by MongoDB on top of our Azure Cosmos DB infrastructure. This allows open-source MongoDB drivers and applications using our supported set of features<\/a>. Azure Cosmos DB provides global distribution, elastic scalability, automatic sharding, and many more features<\/a>.<\/p>\n

How can I get the Mongo shell?<\/h3>\n

It\u2019s simple! Just check the Data Explorer tab and click on Open Mongo Shell.<\/p>\n

\"Image<\/p>\n

Depending on your account\u2019s specific configuration, you might get the following prompt. Click on Complete setup<\/strong>. This will also enable the Notebooks feature<\/a> in your account!<\/p>\n

\"Image<\/p>\n

After that, the Mongo shell b<\/strong>utton<\/strong> will open a ta<\/span>b with an instance that is already connected to the database. And Voil\u00e1! You can now execute some Mongo scripts directly on your databases and collections.<\/span>\"Image<\/p>\n

It\u2019s also worth noting that this Mongo shell has version compatibility with MongoDB v3.6<\/strong>.<\/strong><\/p>\n

What can I do with it?<\/h3>\n

Here are some Cosmos DB-specific commands of what you can do with the Mongo shell. For a complete list of Mongo shell command extensions for Azure Cosmos DB, see MongoDB extension commands for Azure Cosmos DB\u2019s API for MongoDB<\/a><\/p>\n

InsertMany as a batch<\/strong><\/h5>\n

This isn\u2019t particularly new, but I just wanted to bring up that you can insert an array of objects as a single batch using the InsertMany()<\/span>\u00a0 function like this:<\/p>\n

db.test.insertMany([{ _id: 1}, {_id: 2}, {_id: 3}])<\/pre>\n
This gives you the advantage of using a single network request to insert a few documents at a time. How did this insert operation perform? Let’s take a look in the next section.<\/p>\n
Get the request’s statistics\u00a0<\/strong><\/h5>\n
Something that is specific of Cosmos DB is the fact that every database request has an associated Request Units charge<\/a>. You can retrieve this, along with the name, duration and ActivityId of the last operation that was executed with this command:<\/p>\n
db.runCommand({ getLastRequestStatistics: 1 } )<\/pre>\n
This will output something like this:<\/p>\n
{\r\n    \"CommandName\" : \"insert\",\r\n    \"RequestCharge\" : 12.28,\r\n    \"RequestDurationInMilliSeconds\" : NumberLong(120),\r\n    \"ActivityId\" : \"956e2374-f302-409f-9c61-ccb8ba9f14db\",\r\n    \"ok\" : 1\r\n}<\/pre>\n
You can use the output of this command to estimate the Request Units that your collection will need. <\/span>Speaking of RU’s, here’s how you can create and assign RU’s to databases and collections.<\/span><\/p>\n
Create new databases with database-level throughput<\/strong><\/h5>\n
You can create resources in the Cosmos DB-style by using the db.runCommand()<\/span>\u00a0 with a custom action.<\/p>\n
For example, if you want to create a new database, and assign Database-level Throughput on it<\/a>, you can issue the CreateDatabase<\/span> custom command just like this:<\/p>\n
\/\/ First, execute the use command with a new database name\r\nuse newDatabase;\r\n\/\/ Now run the command to create the database. \r\n\/\/ Using offerThroughput parameter will create it as a database-level throughput type.\r\ndb.runCommand({ customAction: \"CreateDatabase\", offerThroughput: 400});<\/pre>\n
If you ever needed to update the throughput of your database, you can just execute the UpdateDatabase<\/span>\u00a0command.<\/p>\n
\/\/ First, use an existing database\r\nuse existingDatabase;\r\n\/\/ Now you can update its database-level throughput.\r\ndb.runCommand({ customAction: \"UpdateDatabase\", offerThroughput: 500});<\/pre>\n
The following section will show you how to create collections with dedicated throughput.<\/p>\n
Create new collections<\/strong><\/h5>\n
For collections, the process looks very similar. You can issue the CreateCollection<\/span>\u00a0custom command with the below parameters:<\/p>\n
\/\/ This command assumes that you are using the database that you want to create this collection in.\r\n\/\/ If you don't specify the offerThroughput parameter, this collection will need to be in a database with database-level throughput.\r\ndb.runCommand({ customAction: \"CreateCollection\", collection: \"newCollection\", offerThroughput: 1000});<\/pre>\n
Alternatively, if you want to create a sharded collection<\/strong>, also known as unlimited collection, you can issue the same custom command, but now with a shardKey parameter:<\/p>\n
\/\/ The shardkey specified will be used to distribute the data across multiple shards.\r\ndb.runCommand({ customAction: \"CreateCollection\", collection: \"newCollection\", offerThroughput: 1000, shardKey: \"pk\" });<\/pre>\n
After running this, all documents will be required to contain the above specified partition key. Read more on partitioning in the documentation<\/a>.<\/p>\n
Troubleshooting<\/h3>\n
If you experience any connectivity issues with the Mongo shell, just close the tab and open a new one in the Data Explorer. This should solve any connectivity problems.<\/p>\n
One feature that currently isn’t supported if your Cosmos DB account has VNET integration<\/a>\u00a0enabled. This is currently under progress and should be available sometime soon.<\/p>\n
Next steps<\/h3>\n