April 25th, 2025

Getting Started with Azure Cosmos DB Using the Python SDK

Gwyneth Peña-Siguenza
Sr. Cloud Advocate

If you’re new to Azure Cosmos DB and looking to build applications with Python, you’re in the right place. I’ve created a four-part video series designed to take you from the basics to practical, real-world querying techniques—no prior experience required. Whether you’re setting up your first database, learning how to model your data, or optimizing your queries, this series will help you build confidence with each step.

This blog post is your companion guide. It introduces key concepts, outlines what each video covers, and provides helpful context so you can follow along more effectively. Whether you’re a student, a data enthusiast, or a backend developer exploring NoSQL for the first time, you’ll find value here.

🔍 Key Concepts

Before diving into the code and videos, here are some terms you need to know:

🌐 Azue Cosmos DB Account

An Azure  Cosmos DB account is the top-level resource that represents your entry point into the service. You can think of it like your overall database service instance. In the video series, mine is named bookrecommender, but you can name yours anything.

📁 Database

Inside your account, you’ll create a database. This is where you logically group containers. In my demo, it’s called BookRecommendationsDB.

📦 Container

A container holds your JSON documents (items). It’s the equivalent of a collection in MongoDB or a table in a relational DB. I created one named books.

🔑 Partition Key

This is super important for performance and scalability. A partition key determines how data is distributed. For this demo, I used /category, which means items are partitioned based on the category field in each document.

🛠️ Prerequisites

Make sure you have the following setup before following along:

  • ✅ Azure Cosmos DB account using the NoSQL API
  • ✅ One database (e.g., BookRecommendationsDB)
  • ✅ One container (e.g., books) with /category as the partition key
  • Azure CLI installed and logged in
  • Azure Identity (a managed identity or service principal with access to Azure Cosmos DB)
  • ✅ Python 3.11 or higher
  • ✅ Required Python packages installed:
pip install azure-cosmos azure-identity python-dotenv
  • ✅ .env file with your configuration (use .env-sample as a template)
  • Clone the series GitHub repository:
git clone https://github.com/madebygps/cosmosdb-python-101

📼 Series Overview

Each video in the series focuses on a key aspect of using Azure Cosmos DB with Python. Below is a quick summary, but make sure to watch the videos for the full walkthroughs and code demos!

We’ve put them all in a playlist for easier access.

1. 5-Minute Setup Guide

In this intro video, I show you how to:

  1. Authenticate with Azure using Azure Identity
  2. Connect to your Azure Cosmos DB account
  3. List all databases and containers

Run it with: python setup.py

2. Creating and Reading Documents

Here, we dig into:

  1. Creating new items with nested objects and arrays
  2. Reading all items from a container
  3. Retrieving an item by ID and partition key

Run it with: python creating_reading.py

3. Updating and Deleting Items

Learn how to:

  1. When to use upsert
  2. Update an existing document using replace_item
  3. Delete items by their ID and partition key

Run it with: python updating_deleting.py

4. Querying

This video dives deep into querying:

  1. WHERE clause filters
  2. Parameterized queries (safer and cleaner)
  3. Projections to return specific fields
  4. Array contains operations (even case-insensitive!)
  5. Cross-partition queries

Run it with: python querying.py

🎯 Wrap-Up

This series is designed to help you get up and running quickly with Azure Cosmos DB using Python—from setting up your environment to writing real-world queries that bring your data to life.

Whether you’re just starting out with NoSQL or looking to deepen your understanding of scalable cloud databases, these videos and scripts provide a solid foundation. The goal is not just to teach you how to use the SDK, but also why certain design and query decisions matter when building modern, cloud-native applications.

Go watch the videos, follow along with the code, and experiment with your own data. And if you find the content helpful, don’t forget to subscribe and share it with a fellow Python developer who might benefit, too.

This is just the beginning—we’ll be sharing more advanced scenarios, performance tips, and integration examples in upcoming videos. Stay tuned and keep building with Azure Cosmos DB!

Leave a review

Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we’ll gift you $50. Get started here.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.

Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on XYouTube, and LinkedIn.

Author

Gwyneth Peña-Siguenza
Sr. Cloud Advocate

Gwen is a Cloud Advocate at Microsoft, focused on helping others build on Azure. In her spare time, she builds the open-source courseware LearnToCloud, documents her learnings and career on YouTube, reads, and spends time with her family, friends, and cats.

0 comments