Azure Cosmos DB is a fully managed NoSQL database designed for modern app development. Microsoft states that “…any web, mobile, gaming, and IoT application that needs to handle massive amounts of data, reads, and writes at a global scale with near-real response times for a variety of data will benefit from Cosmos DB…”.

In this post I want to demonstrate how to build an Azure Cosmos DB using simple Azure CI commands and then access the database to insert some records and finally query the data.

Creating the Database

To create the Cosmos DB, I logged into the Azure Portal and opened Azure Cloud CLI. Once a terminal session is established, I started by creating an environment variable to hold the Azure Cosmos DB account name (so I don’t have to type the same value each time in the commands). Using variables with the Azure CLI also allows reuse of commands, either part or as part of scripts.

Since the database account name must be unique across all Azure Cosmos DB instances, I used the following command to generate a random database account name, by using Bash $RANDOM, and stored the value it in an environment variable to use later. The random function in bash gives you a (more or less) random integer between 0 and 32767.

export NAME=cosmos$RANDOM

Next I used the Azure CLI cosmosdb create command to create a new Azure Cosmos DB account. The following command created a new Azure Cosmos DB account with the specified (random) name (it assumes that the Azure Resource Group “jamesdouglasmillerRG “ is already created):

az cosmosdb create

–name $NAME

–kind GlobalDocumentDB

–resource-group jamesdouglasmillerRG

The command takes a few minutes to complete then the Cloud Shell displays the resulting settings as a JSON object for the new account. JavaScript Object Notation (or JSON) is a standard text-based format for representing structured data based on JavaScript object syntax and is commonly used for transmitting data:

Now I want to create a “Motorcycles” database within the Azure Cosmos DB account just created, so I can run the cosmosdb database create command. This command takes a db-name parameter that we’ll set to Motorcycles since this database will hold motorcycle inventory data.

az cosmosdb sql database create

–account-name $NAME

–name “Motorcycles”

–resource-group jamesdouglasmillerRG

This command runs quickly and produce output something like the following:

Finally, I want to create a “bikes” container in my Motorcycles database by running the cosmosdb sql container create command:

az cosmosdb sql container create

–account-name $NAME

–database-name “Motorcycles”

–name “bikes”

–partition-key-path “/productId”

–throughput 1000

–resource-group jamesdouglasmillerRG

Now that I have an Azure Cosmos DB account, database, and container, I can add some data!

Adding data using Data Explorer

The Azure Cosmos DB Data Explorer is a tool included in the Azure portal that is used to manage data stored in an Azure Cosmos DB. It provides a UI for navigating and viewing data, querying and modifying data, and creating and running stored procedures. The Data Explorer is a excellent tool to get acquainted with Azure Cosmos DB. In the next few steps we’ll use the Data Explorer to add data to our new Cosmos DB and then query it.

Accessing the Azure DB Data Explorer

To access the data explorer, first sign into the Azure portal and select All services. Next, click Databases, then Azure Cosmos DB, and then select the DB just created.

Find and select Data Explorer (you may need to search for it):

Within the Data Explorer expand the Motorcycles database in the SQL API pane:

To add some data, you need to create a new JSON document, so if you expand bikes (in the SQL API pane), select Items, and then New Item in the toolbar you can paste in a document (overwriting any content shown). My first motorcycle record (in JSON format) is shown below:

Once you paste in the document you click Save in the toolbar to commit the data. To create and save another document (add another motorcycle record) you can again select New Item and paste another JSON object and then save it:

Did it work? You can confirm the documents have been saved in the database by clicking Items on the left-hand menu:

You should see two items listed, verifying that we’ve added two documents (my two motorcycles) each representing a bike in my motorcycle inventory.

Using SQL to Query the Data

You can write and run queries against the Cosmos DB database using the Data Explorer by selecting New SQL Query from the toolbar as shown here:

Then we can write a SQL-type query to return the data we just added:

SELECT p.price, p.description, p.productId

FROM bikes p

ORDER BY p.price ASC

To run the query, you select Execute Query. This query returns all results in the database.

Summary

In this post I’ve created an Azure Cosmos DB account, database, and container using the Azure CLI and then used the Azure Data Explorer to add and query data providing at least the basics of how Azure Cosmos DB works and how one might use it as a foundation for are larger database project.