Integrate Python Apps with Azure Cosmos DB

This skill teaches an agent to use the azure-cosmos Python SDK directly against Azure Cosmos DB's NoSQL API: creating a CosmosClient, getting a DatabaseProxy and ContainerProxy, and performing item-level CRUD (create_item, read_item, replace_item, upsert_item, delete_item) plus in-partition and cross-partition SQL queries (query_items) with parameterized @param syntax. It covers defining single and hierarchical (preview) partition keys, setting and reading provisioned throughput in RU/s, and an async client (azure.cosmos.aio) for high-throughput scenarios. Databases and containers can be created idempotently with create_database_if_not_exists() and create_container_if_not_exists(), and an existing container's provisioned throughput can be read and changed with read_offer() and replace_throughput().

Use it when writing or reviewing Python code that talks to Cosmos DB directly through the official SDK - container setup, item CRUD, queries, partitioning, or throughput management. It is the low-level SDK reference, not an application architecture guide: for a layered service (FastAPI router, service layer, Pydantic models, TDD) built on top of this SDK, use a separate Cosmos DB service-implementation skill instead of this one. Its stated best practices: always specify a partition key for point reads and queries, prefer read_item over a query for single-document retrieval, use upsert_item for idempotent writes, avoid cross-partition queries where possible, and design the partition key up front for even data distribution rather than fixing a hot partition later.

Inputs: COSMOS_ENDPOINT, COSMOS_DATABASE, and COSMOS_CONTAINER as environment variables, a DefaultAzureCredential, and, per call, an item body (with a required unique id and the partition key field), a partition key value, or a SQL query string with named parameters. Outputs: created, read, and updated item dictionaries, query result iterables (sync or async for), an offer object from read_offer() reporting current RU/s, and CosmosHttpResponseError exceptions carrying a status_code - 404 for missing items, 429 for rate limiting, with an x-ms-retry-after-ms header.

Azure Cosmos DB NoSQL API, Azure Identity (DefaultAzureCredential, including the async azure.identity.aio variant), and the skill's own bundled scripts/setup_cosmos_container.py CLI for creating containers with partitioning, throughput, and indexing already configured. Reference files cover partition key strategies (including hierarchical keys and hot-partition mitigation) and query patterns such as optimization, aggregations, pagination, transactions, and change feed.

pip install azure-cosmos azure-identity

Python developers writing direct Cosmos DB client code - CRUD, queries, partition and throughput management - rather than building a full service architecture on top of it.