Azure Cosmos DB for Python
A practical guide for building reliable Python applications on Azure Cosmos DB’s NoSQL API.
The skill recommends DefaultAzureCredential, discourages keys, uses parameterized queries, and emphasizes deterministic client cleanup, providing partial least-privilege and data-flow safety guidance. However, create, replace, delete, and throughput-changing operations lack user confirmation, rollback, or recovery guidance; sensitive-data handling, dependency security, and complete source attribution are also missing, so points are deducted.
It covers sync/async lifecycle management, common HTTP statuses, and retry feedback, making the happy path plausible. However, the core setup omits the PartitionKey import, several advanced examples have insufficient concurrency/API-compatibility/edge-case treatment, and no skill-specific execution evidence is supplied; the static cap keeps this at 8.
Triggers and scenarios for Python SDK CRUD, queries, and partition keys are reasonably clear, and cross-partition queries are identified as a costly non-preferred case. Input prerequisites, non-fit boundaries, compatibility ranges, and conditional fallback guidance remain incomplete; the documentation is English-only and gives no Chinese-language or mainland-China reachability guidance, so points are deducted.
The document has installation, environment variables, authentication, workflows, references, and a script entry, plus MIT licensing, author metadata, and version 1.0.0. It lacks a skill-specific changelog, explicit maintenance/update path, FAQ, and systematic troubleshooting; the referenced files and script are not included in the supplied evidence, preventing a full score.
The material covers CRUD, queries, pagination, aggregations, transactions, change feed, and partition design, offering useful direct guidance for common Cosmos DB coding tasks. However, the examples are not a complete runnable implementation and require checking imports, permissions, service prerequisites, and potentially unsafe advanced patterns; static evidence supports only 6.
The skill, repository README, license, security policy, and CI files are auditable primary repository materials, and the repository reports evaluation and testing workflows. There are no path-specific committed tests, real execution results, or independent corroboration in the supplied files, so this remains 4.
- Before executing writes, deletes, throughput changes, or transaction examples, confirm the target account, database, container, permissions, and recovery plan with the user.
- The core database/container example omits the PartitionKey import; do not assume every advanced example is compatible with the installed azure-cosmos version.
- Add SDK version constraints, skill-specific tests, troubleshooting, sensitive-data guidance, and Chinese/mainland-China reachability notes.
What does this skill do, and when should you use it?
This skill targets the Azure Cosmos DB NoSQL API and covers client lifecycle, databases, containers, document CRUD, queries, partition keys, and throughput. It includes both synchronous and asynchronous Python examples and recommends DefaultAzureCredential for authentication. The guidance emphasizes context managers for clients and async credentials, plus explicit partition-key usage for efficient operations. It is a good fit for developers integrating Cosmos DB into Python services or scripts.
Provides the installation command for azure-cosmos and azure-identity; documents COSMOS_ENDPOINT, COSMOS_DATABASE, COSMOS_CONTAINER, and production AZURE_TOKEN_CREDENTIALS settings; explains CosmosClient, DatabaseProxy, and ContainerProxy; demonstrates database and container creation, item creation, point reads, replacement, upserts, deletion, parameterized queries, cross-partition queries, projections, throughput reads and updates; and includes synchronous, asynchronous, and CosmosHttpResponseError handling examples.
- A Python developer needs to create or retrieve a Cosmos DB database and a partitioned container.
- A backend engineer needs document create, point-read, replace, upsert, and delete operations.
- A service developer needs parameterized queries within a partition or an explicitly controlled cross-partition query.
- A high-throughput Python application needs the asynchronous Cosmos client and async DefaultAzureCredential.
- An application or operations developer needs to inspect or change provisioned container throughput.
What are this skill's strengths and limitations?
- Covers both synchronous and asynchronous clients with practical common-operation examples.
- Clearly promotes DefaultAzureCredential, context managers, and parameterized queries.
- Addresses partition keys, cross-partition queries, throughput, and 404/429 handling.
- Points to reference material for partitioning and query patterns, plus a container setup script.
- Focused on Python and the Azure Cosmos DB NoSQL API rather than other languages or API models.
- It identifies cross-partition queries as more expensive but provides no concrete cost or performance benchmarks.
- The source does not provide skill-specific test results or test scenarios.
- The async pattern requires azure.identity.aio and separate context managers for the async client and credential.
How do you install this skill?
Run pip install azure-cosmos azure-identity. To install the broader Agent Skills collection, run npx skills add microsoft/skills and select the required skill in the wizard; the collection is installed into the selected agent directory, such as .github/skills/. The source does not document a dedicated command for installing only azure-cosmos-py.
How do you use this skill?
In an Agent Skills-compatible coding agent, ask: “Use azure-cosmos and azure-identity to implement document CRUD and parameterized queries for a Cosmos DB NoSQL container with a partition key.” Before running the generated code, configure COSMOS_ENDPOINT, COSMOS_DATABASE, and COSMOS_CONTAINER; for production DefaultAzureCredential usage, also set AZURE_TOKEN_CREDENTIALS=prod or a specific credential name.
How does this skill compare with similar options?
Compared with connection strings, account keys, or API keys, the skill favors DefaultAzureCredential so the same code can work across local development and Azure environments while preserving Entra auditing and credential rotation practices.