Integrate Python Apps with Azure Cosmos DB

Azure Cosmos DB SDK for Python is a client library for Azure Cosmos DB's NoSQL API, a globally distributed, multi-model database. It has a three-level client hierarchy: CosmosClient for account-level operations, DatabaseProxy (via client.get_database_client()), and ContainerProxy (via database.get_container_client()), authenticated with DefaultAzureCredential, with an async mirror of the whole API.

Setup creates or fetches a database and a container with a partition key via create_database_if_not_exists/create_container_if_not_exists. Item operations cover create (a dict with a required id and partition-key field), read (requiring both the item id and its partition key), replace (read, mutate, then write back the whole document), upsert (create if missing, replace if present - the SDK's own recommendation for idempotent writes), and delete. Queries run SQL-like syntax with parameterized values, scoped to a single partition (efficient) or explicitly marked cross-partition (enable_cross_partition_query=True, called out as more expensive and to be used sparingly) - queries can also project specific fields instead of the whole document, and read_all_items() reads across all partitions. Partition keys can be a single path or, in preview, a hierarchical multi-level key (for example tenant ID then user ID). Container throughput is provisioned in RU/s at creation, readable via read_offer() and adjustable with replace_throughput().

Use it when building a Python application on Cosmos DB's NoSQL API that needs point reads/writes and queries against partitioned containers. Always specify the partition key for point reads and queries - the skill's own best practices call this out as the single most important performance lever, and cross-partition queries should be the exception, not the default query pattern.

Input is a document (dict) with an id and partition-key field, or a parameterized SQL-like query. Output is the created/read/updated document, a query result iterator, or throughput/offer information. Errors surface as CosmosHttpResponseError, checked by status code - 404 for a missing item, 429 for rate limiting (with a x-ms-retry-after-ms header telling you how long to wait). Install it with:

pip install azure-cosmos azure-identity

Its own best practices: always specify the partition key for point reads and queries, use parameterized queries to prevent injection and improve caching, avoid cross-partition queries when possible, use upsert_item for idempotent writes, use the async client for high-throughput scenarios, design the partition key for even data distribution, and prefer read_item over a query for single-document retrieval.

It's the azure-cosmos package paired with azure-identity for DefaultAzureCredential authentication; the skill also ships reference material on partitioning strategy and hot-partition mitigation, query optimization/pagination/change feed, and a CLI script for creating containers with partitioning, throughput, and indexing configured.

Python developers building applications on Azure Cosmos DB's NoSQL API who need efficient partition-aware CRUD and queries, provisioned throughput control, and idempotent write patterns.