Azure Cosmos DB Interaction through Python

What is Cosmos DB?

Azure Cosmos DB is a fully managed NoSQL and relational database for modern app development. Azure Cosmos DB offers single-digit millisecond response times, automatic and instant scalability, along with guaranteed speed at any scale. Business continuity is assured with SLA-backed availability and enterprise-grade security.

In this article, we will see how to build a data layer in Python for Azure Cosmos DB using PythonSDK. This simple application shows simple CRUD operations (insert, update, list and delete) using a simple data provided as input to Cosmos DB.

Below is the sequence that we are going to follow in this article:

  1. Create an Azure Cosmos DB account
  2. Setup the dev environment
  3. Connect to account, create database and container
  4. Create a sample input data.
  5. Write our CRUD operations
  6. Login to Cosmos DB and verify our data.

1. Creating an Azure Cosmos DB account.

  • Login to Azure portal Home - Microsoft Azure
  • Search for “Azure Cosmos DB” in the Resource Blade as shown in the screenshot below.
    Azure cosmos DB
  • Click on “+Create” or click on “Create Azure Cosmos DB account” option as shown in the below screenshot.
    It will open a Suite of APIs supported by Cosmos DB as shown below. For this example, we will choose NoSQL API. Click on “Create” under Azure Cosmos DB for NoSQL marked as below.
  • It will open the provisioning screen for Cosmos DB. Provide the details as shown below and click on “Review + Create”.
    Azure Cosmos DB

Note. The Account Name for Cosmos DB should be unique globally since this will be part of the endpoint URL that you will be using to communicate with this account.

Go to your Resource group, click on the Azure Cosmos DB service created in your resource group. On the “Settings” menu on the left side, click on “Keys”.


From the resultant screen, copy the URI as well as the PRIMARY KEY and keep it in a notepad. We will be using this in our code to read-write into our container.

Read-write Keys

Our Database steps are complete. Will move onto the coding part.

2. Setup the Dev Environment

My choice of programming language is Python and hence, the below example will be based on Python. However, you can choose your own language.

To try out the below example, you will need to have Python installed in your system. I have installed 3.9.7 in my system. If possible, install the latest 3.10.X version.

First step is to install the required libraries. To install python libraries the command to be used is “pip install <LibraryName>. To interact with Cosmos DB, we will need install azure.cosmos as shown below:


Since I have already installed the library, it is showing as already satisfied. If it is not installed previously, it will install the library.

  • Open the Python IDLE Shell.
  • In the IDLE shell, click on File -> New and open a new file
  • The architecture of Cosmos DB is such that you have the Azure Cosmos DB account, under which you will have the Database. The Container will be created under the Database and individual Items will be inserted in the Container. This will be the same sequence which we will be following.

First step is to import the CosmosClient and PartitionKey class from the azure.cosmos module. CosmosClient will have the method to instantiate the Cosmos DB account which we will then use to create the Database. PartitionKey class is used to define the Partition Key for the Container items. Paste the below command in the new IDLE Shell file.

from azure.cosmos import CosmosClient,PartitionKey

3. Connect to account, create database and container

The next step is to provide the Endpoint URI and the Key to access the Cosmos DB account.


CONTAINER_NAME = "products"

Note. I have provided the endpoint and key here in the open for illustration purpose. However, the best practice is to store the secrets in Keyvault and access it from there.

Next step is to instantiate the Cosmos DB with the below command:

client = CosmosClient(url=ENDPOINT, credential=KEY)

With the help of the “client” object we will now create the Database object with the below command. DATABASE_NAME is the constant value provided at the beginning.

database = client.create_database_if_not_exists(id=DATABASE_NAME)

Once the “database” object is created, we will use it to create the container object. We will also be defining the Partition Key using the PartitionKey class imported in the first line. Use the below codes to perform the same.

key_path = PartitionKey(path="/categoryId")

container = database.create_container_if_not_exists(


/CategoryId is one of the properties in the JSON input that we will be providing. 400 Throughput is the maximum throughput offered for a Free Tier. Throughput is nothing but the number of request unit per second. CONTAINER_NAME is provided as a constant at the beginning of the code.

4. Create a sample input data

Below are the inputs that we are going to store in the DB.

new_item1 = {
    "id": "80b63682-b93a-4c77-aad2-65501347265f",
    "categoryId": "61dba35b-4f02-45c5-b173-c6badc0cbd79",
    "categoryName": "SUV",
    "name": "Brezza",
    "Drive": "2WD",

new_item2 = {
    "id": "80b63683-b93b-4c77-agd2-65501384965f",
    "categoryId": "61dsc35b-4e50-45c5-b728-c6banm8cbd79",
    "categoryName": "Hatchback",
    "name": "Baleno",
    "Drive": "2WD",

Through below steps, we are inserting the inputs into our containers.


5. Write our CRUD operations

Through below code we will read the container and populate the Item with ID “80b63683-b93b-4c77-agd2-65501384965f” and CategoryID as “61dsc35b-4e50-45c5-b728-c6banm8cbd79”

item = container.read_item(
item = "80b63683-b93b-4c77-agd2-65501384965f",

partition_key = "61dsc35b-4e50-45c5-b728-c6banm8cbd79")


On executing the code, you should be viewing the output as below.

Execution code

As you can see, the Database “Toyota” and Container “products” has been created and the inputs were inserted, which were then populated through read_item method.

6. Login to Cosmos DB and verify our data

Go to the Azure Portal and go to the Cosmos DB account you had created. On the left hand side, click on “Data Explorer” You will see the output as shown below:

Data explorer

This is how you programmatically converse with Cosmos DB.

Similar Articles