Native Mongo shell on Azure Cosmos DB API for MongoDB now in preview

Luis Bosquez

We are happy to announce the preview release for native Mongo shell v3.6.8 on the Data Explorer for Azure Cosmos DB’s API for MongoDB!

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 or in its stand-alone version. Check the highlighted note in this article to know which Azure Regions are supported today.

What is the Azure Cosmos DB API for MongoDB?

If you haven’t 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. Azure Cosmos DB provides global distribution, elastic scalability, automatic sharding, and many more features.

How can I get the Mongo shell?

It’s simple! Just check the Data Explorer tab and click on Open Mongo Shell.

Depending on your account’s specific configuration, you might get the following prompt. Click on Complete setup. This will also enable the Notebooks feature in your account!

After that, the Mongo shell button will open a tab with an instance that is already connected to the database. And Voilá! You can now execute some Mongo scripts directly on your databases and collections.

It’s also worth noting that this Mongo shell has version compatibility with MongoDB v3.6.

What can I do with it?

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’s API for MongoDB

InsertMany as a batch

This isn’t particularly new, but I just wanted to bring up that you can insert an array of objects as a single batch using the InsertMany()  function like this:

db.test.insertMany([{ _id: 1}, {_id: 2}, {_id: 3}])

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.

Get the request’s statistics 

Something that is specific of Cosmos DB is the fact that every database request has an associated Request Units charge. You can retrieve this, along with the name, duration and ActivityId of the last operation that was executed with this command:

db.runCommand({ getLastRequestStatistics: 1 } )

This will output something like this:

{
    "CommandName" : "insert",
    "RequestCharge" : 12.28,
    "RequestDurationInMilliSeconds" : NumberLong(120),
    "ActivityId" : "956e2374-f302-409f-9c61-ccb8ba9f14db",
    "ok" : 1
}

You can use the output of this command to estimate the Request Units that your collection will need. Speaking of RU’s, here’s how you can create and assign RU’s to databases and collections.

Create new databases with database-level throughput

You can create resources in the Cosmos DB-style by using the db.runCommand()  with a custom action.

For example, if you want to create a new database, and assign Database-level Throughput on it, you can issue the CreateDatabase custom command just like this:

// First, execute the use command with a new database name
use newDatabase;
// Now run the command to create the database. 
// Using offerThroughput parameter will create it as a database-level throughput type.
db.runCommand({ customAction: "CreateDatabase", offerThroughput: 400});

If you ever needed to update the throughput of your database, you can just execute the UpdateDatabase command.

// First, use an existing database
use existingDatabase;
// Now you can update its database-level throughput.
db.runCommand({ customAction: "UpdateDatabase", offerThroughput: 500});

The following section will show you how to create collections with dedicated throughput.

Create new collections

For collections, the process looks very similar. You can issue the CreateCollection custom command with the below parameters:

// This command assumes that you are using the database that you want to create this collection in.
// If you don't specify the offerThroughput parameter, this collection will need to be in a database with database-level throughput.
db.runCommand({ customAction: "CreateCollection", collection: "newCollection", offerThroughput: 1000});

Alternatively, if you want to create a sharded collection, also known as unlimited collection, you can issue the same custom command, but now with a shardKey parameter:

// The shardkey specified will be used to distribute the data across multiple shards.
db.runCommand({ customAction: "CreateCollection", collection: "newCollection", offerThroughput: 1000, shardKey: "pk" });

After running this, all documents will be required to contain the above specified partition key. Read more on partitioning in the documentation.

Troubleshooting

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.

One feature that currently isn’t supported if your Cosmos DB account has VNET integration enabled. This is currently under progress and should be available sometime soon.

Next steps

• Check out our QuickStart for Azure Cosmos DB’s API for MongoDB with the Mongo shell!
• If you have any feedback, let us know in the comments!
• If you have any new feature ideas for Mongo shell or Azure Cosmos DB’s API for MongoDB Let us know at our UserVoice page.

Luis Bosquez Program Manager, Cosmos DB

Follow