Azure Cosmos DB Tutorial

Introduction: Azure Cosmos DB is a fully managed NoSQL database service that provides fast and predictable performance, seamless scalability, and high availability with multiple consistency levels to choose from. In this tutorial, we will learn how to create an Azure Cosmos DB account, create and manage databases, collections, and documents using the Azure CLI.

Prerequisites:

  • An Azure account with active subscription.
  • Azure CLI installed on your local machine.
  • Basic knowledge of Azure services and CLI commands.

Step 1: Create a Cosmos DB account To create a Cosmos DB account, use the following Azure CLI command:

az cosmosdb create --name <cosmosdb-account-name> --kind GlobalDocumentDB --resource-group <resource-group-name> --default-consistency-level <consistency-level>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account you want to create.
  • <resource-group-name>: Name of the resource group where you want to create the Cosmos DB account.
  • <consistency-level>: Default consistency level for the account, which can be one of the following values: strong, bounded-staleness, session, consistent-prefix, or eventual.

For example, to create a Cosmos DB account with the name “mycosmosdb” in the resource group “myresourcegroup” with the default consistency level “session”, use the following command:

az cosmosdb create --name mycosmosdb --kind GlobalDocumentDB --resource-group myresourcegroup --default-consistency-level session

Step 2: Create a database To create a database in the Cosmos DB account, use the following Azure CLI command:

az cosmosdb database create --account-name <cosmosdb-account-name> --name <database-name> --resource-group <resource-group-name>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where you want to create the database.
  • <database-name>: Name of the database you want to create.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.

For example, to create a database with the name “mydatabase” in the Cosmos DB account “mycosmosdb” located in the resource group “myresourcegroup”, use the following command:

az cosmosdb database create --account-name mycosmosdb --name mydatabase --resource-group myresourcegroup

Step 3: Create a collection To create a collection in the database, use the following Azure CLI command:

az cosmosdb collection create --account-name <cosmosdb-account-name> --database-name <database-name> --name <collection-name> --resource-group <resource-group-name> --partition-key-path <partition-key-path> --throughput <throughput>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where the database is located.
  • <database-name>: Name of the database where you want to create the collection.
  • <collection-name>: Name of the collection you want to create.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.
  • <partition-key-path>: Partition key path for the collection. The path should start with a leading slash (/) and can be any property in the document.
  • <throughput>: Throughput value for the collection, which determines the amount of resources allocated for the collection. The value must be a multiple of 100.

For example, to create a collection with the name “mycollection” in the database “mydatabase” located in the Cosmos DB account “mycosmosdb” with partition key path “/myPartitionKey” and throughput of 400, use the following command:

az cosmosdb collection create --account-name mycosmosdb --database-name mydatabase --name mycollection --resource-group myresourcegroup --partition-key-path /myPartitionKey --throughput 400

Step 4: Add documents to the collection To add documents to the collection, use the following Azure CLI command:

az cosmosdb document create --account-name <cosmosdb-account-name> --database-name <database-name> --collection-name <collection-name> --resource-group <resource-group-name> --content <document-content>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where the database and collection are located.
  • <database-name>: Name of the database where the collection is located.
  • <collection-name>: Name of the collection where you want to add the document.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.
  • <document-content>: Content of the document to be added in JSON format.

For example, to add a document with the following content to the collection “mycollection” in the database “mydatabase” located in the Cosmos DB account “mycosmosdb” in the resource group “myresourcegroup”:

{
    "id": "1",
    "name": "John Doe",
    "age": 30,
    "myPartitionKey": "myPartitionKeyValue"
}

Use the following command:

az cosmosdb document create --account-name mycosmosdb --database-name mydatabase --collection-name mycollection --resource-group myresourcegroup --content '{"id": "1", "name": "John Doe", "age": 30, "myPartitionKey": "myPartitionKeyValue"}'

Step 5: Query the collection To query the collection, use the following Azure CLI command:

az cosmosdb sql query --account-name <cosmosdb-account-name> --database-name <database-name> --collection-name <collection-name> --resource-group <resource-group-name> --query <query-expression>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where the database and collection are located.
  • <database-name>: Name of the database where the collection is located.
  • <collection-name>: Name of the collection you want to query.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.
  • <query-expression>: Query expression in SQL syntax.

For example, to query all documents in the collection “mycollection” in the database “mydatabase” located in the Cosmos DB account “mycosmosdb” in the resource group “myresourcegroup”, use the following command:

az cosmosdb sql query --account-name mycosmosdb --database-name mydatabase --collection-name mycollection --resource-group myresourcegroup --query "SELECT * FROM c"

Step 6: Delete the collection, database, and Cosmos DB account To delete the collection, use the following Azure CLI command:

az cosmosdb collection delete --account-name <cosmosdb-account-name> --database-name <database-name> --name <collection-name> --resource-group <resource-group-name>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where the database and collection are located.
  • <database-name>: Name of the database where the collection is located.
  • <collection-name>: Name of the collection you want to delete.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.

For example, to delete the collection “mycollection” in the database “mydatabase” located in the Cosmos DB account “mycosmosdb” in the resource group “myresourcegroup”, use the following command:

az cosmosdb collection delete --account-name mycosmosdb --database-name mydatabase --name mycollection --resource-group myresourcegroup

To delete the database, use the following Azure CLI command:

az cosmosdb database delete --account-name <cosmosdb-account-name> --name <database-name> --resource-group <resource-group-name>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account where the database is located.
  • <database-name>: Name of the database you want to delete.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.

For example, to delete the database “mydatabase” located in the Cosmos DB account “mycosmosdb” in the resource group “myresourcegroup”, use the following command:

az cosmosdb database delete --account-name mycosmosdb --name mydatabase --resource-group myresourcegroup

Finally, to delete the Cosmos DB account, use the following Azure CLI command:

az cosmosdb delete --name <cosmosdb-account-name> --resource-group <resource-group-name>

Here, replace the following placeholders with actual values:

  • <cosmosdb-account-name>: Name of the Cosmos DB account you want to delete.
  • <resource-group-name>: Name of the resource group where the Cosmos DB account is located.

For example, to delete the Cosmos DB account “mycosmosdb” in the resource group “myresourcegroup”, use the following command:

az cosmosdb delete --name mycosmosdb --resource-group myresourcegroup

And that’s it! You have now learned how to create a Cosmos DB account, database, and collection, add documents to the collection, query the collection, and delete the collection, database, and Cosmos DB account using Azure CLI commands.