Azure Cosmos DB is a NoSQL and relational database from Microsoft. It is a document-like database in the Azure cloud. Azure Cosmos DB offers modern app development, good response times, scalability, and speed at any scale.

Introduction to Azure Cosmos DB

Azure Cosmos DB handles database administration, automatic updates and patching management, and serverless and auto-scaling capacity management to achieve capacity with demand. Azure Cosmos DB supports document, key-value, wide-column, and graph databases.

Data is organized in Collection, and Documents inside a collection. A collection is similar to a table in SQL, and a document is identical to a row in a SQL table. Each document is a JSON-like structure. Besides document collection, Cosmos DB provides other features like Stored Procedures, User Defined Functions, and Triggers.

Managing Azure Cosmos DB documentation using Python

Using its Data Explorer, you can use the Azure portal to work with Cosmos DB. There are many API services available to interact with Cosmos DB. You can use Python with Azure Cosmos DB SQL API SDK and manage databases and JSON documents in Cosmos DB. This API can handle the below operations.

  • Creating Cosmos DB database in Azure and modifying the settings.
  • Creating and modifying containers that store JSON document collection.
  • Allows JSON document operations like creating, reading, updating, and deleting items.
  • Querying the documents in the database by using SQL – like syntax.


We need to have Azure Subscription and a Cosmos DB Account. Creating Azure Subscription and setting up Azure Cosmos DB Account is not in the scope of this blog. It would be best to have a Python environment like PyCharm in your machine to use Azure Cosmos DB SQL API. Below steps describes how to connect to the Cosmos DB account and manage the documents in a Cosmos DB database using this python API.

1. Library installation – Azure Cosmos DB SQL API

You need to install the azure-cosmos module into your Python environment. Open your python environment like PyCharm and install the module.

  • pip install azure-cosmos

2. Azure Cosmos DB Credentials

In order to communicate with Cosmos DB, you need its URI and primary master key. You can find these from the Azure Portal.

Azure Cosmos DB Credentials - URI
Azure Cosmos DB Credentials - Primary key

3. Client

The client is a logical representation of a Cosmos DB account. It is created with the help of Cosmos DB URI and the primary master key obtained from the above step. It helps in configuring and executing requests to the Azure Cosmos DB service.

Azure Cosmos DB service

Azure Cosmos DB SQL API SDK is used to interact with database accounts. When Cosmos DB Account is created, you need to specify the API to use while interacting with documents in the database; it can be SQL, MongoDB, Gremlin, Cassandra, or Azure Table. Once CosmosClient is initialized, you can interact with the primary resource types in Cosmos DB, listed below:

  • Database: Cosmos DB account can have one or more databases. A database may have several containers that are similar to folders.
  • Container: JSON documents are organized as a collection in a container. You can create (insert), read, update, and delete items in a container.
  • Item: Data is organized as items in a dictionary-like representation of a JSON document stored in a container. Each item must include an id key with a value uniquely identifying the item within the container.

4. Query the database

Azure Cosmos DB SQL API database helps in querying the items of a container with the QueryItems() method from CosmosClient class, just like SQL syntax.

Below example queries items from a given container.

querying the items of a container

You can also get individual documents details using read_all_items() method.

read_all_items() method

5. Insert data

In Cosmos DB, data is organized in JSON format with key-value pairs as items. It is possible to have nested and an array of items also. New items can be inserted into a database container by supplying a dictionary containing the data to UpsertItem() method from CosmosClient class. Each item must have an id key with a value that uniquely identifies the item within a container. Below example, inserts multiple random items into the container, with a unique id for each item.

cosmos DB Insert data

6. Delete data

You can delete items from a container, using DeleteItem() method from CosmosClient class. The SQL API in Cosmos DB does not support the SQL DELETE statement.

Below example, delete an item with given id from a container. You need to provide the key-column used for partitionKey.

7. Bulk delete

Sometimes you may face a scenario where you have to delete all documents from a container programmatically, but then there is no easy way to do it directly.

You can achieve this by a work around with the help of Cosmos DB Stored procedures and Azure Cosmos DB SQL API.

  • Create a stored procedure in the Cosmos DB container that runs a select query and deletes the required data.
  • Call the stored procedure from a Python script with the help of Azure Cosmos DB SQL API.

7.1 Create stored procedure in Azure Cosmos DB

In the Azure portal, navigate to the stored procedure section in Cosmos DB account and create new stored procedure with below code.

cosmos DB Bulk delete

7.2 Run the stored procedure from a Python script

Once the stored procedure is created in Azure Cosmos DB you can call it from python script.

Stored Procedure from a Python script

Once above script is executed, you can find no items present in the given container. Execution time depends on the volume of the data present.

8. Complete Script

Complete code is given below for reference. You can play around with it by organizing in a single program or separate methods to perform each operation.

cosmos DB Complete Script


In this blog, we explored the procedure to interact with Azure Cosmos DB python SDK and manage the document collection by using a python API called Cosmos DB SQL API. Also, there are different ways and API services available to achieve this. Whether you are building a web app, a mobile app, or a data intensive IoT solution, Cosmos DB can help you store and access data at scale, with low latency and high throughput. By leveraging its rich features and capabilities you can easily build and deploy applications that meet the demands of today’s digital world. So, if you are looking to take your application development to the next level, we highly recommend giving Azure Cosmos DB a try. With its flexible pricing model and pay-as-you-go options, you can start small and scale-up as your needs grow. So, go ahead and explore the possibilities that Azure Cosmos DB has to offer – you won’t be disappointed.

Ready to explore the power of Microsoft Azure’s cloud services? Learn how Azure Cosmos DB can transform the way you manage and scale your data. As a Microsoft Azure partner we are here to help you get started. Discover the potential of the game-changing solution with us.

Poreddy Ashok
Technical Architect, Analytics

Ready to get started?

Contact us Close