azure-cosmos-py

Overview of azure-cosmos-py skill

The azure-cosmos-py skill helps you work with Azure Cosmos DB from Python when you need document CRUD, partition-aware container design, queries, and authentication setup without guessing the SDK shape. It is best for engineers building or maintaining database code, especially in Azure-first stacks and for azure-cosmos-py for Database Engineering use cases where partitioning and query cost matter as much as basic connectivity.

What this skill is for

Use the azure-cosmos-py skill when your job is to create a reliable Python integration with Cosmos DB NoSQL API, not just “make a client connect.” The repository is tuned for practical tasks: installation, environment variables, auth choices, client hierarchy, container setup, partitioning, and query patterns.

Why it is worth installing

The main value is decision guidance. The skill shows what to configure first, what to avoid in queries, and how to think about partition keys before you write app code. That makes it more useful than a generic prompt when the real blocker is data model or performance fit, not syntax.

Best-fit and misfit cases

This is a strong fit if you need azure-cosmos-py usage guidance for containers, reads, writes, or queries against the NoSQL API. It is a weaker fit if you want relational modeling, bulk analytics, or non-Python SDKs. If your project is not Azure Cosmos DB NoSQL, this skill will be the wrong starting point.

How to Use azure-cosmos-py skill

Install and inspect the right files first

For azure-cosmos-py install, start with the repository skill path and then read the support files that change implementation decisions:

• SKILL.md for the main workflow and auth setup
• references/partitioning.md for partition-key selection
• references/query-patterns.md for query cost and parameterization
• scripts/setup_cosmos_container.py for container creation patterns

The install command shown in the skill is:

pip install azure-cosmos azure-identity

Turn a rough request into a usable prompt

The skill works best when you provide the database shape and the operation goal, not just “help with Cosmos.” Good input includes:

• container name
• example item shape
• partition key path
• whether the goal is read, write, query, or container creation
• local dev vs production auth
• whether cross-partition query is acceptable

Example prompt shape:
“Use azure-cosmos-py to create a container for orders partitioned by /customer_id, then show a Python read/write example using CosmosClient and a parameterized query for all orders in one customer partition.”

Use the workflow that matches your task

For container setup, follow the script and partitioning reference before writing app code. For query work, prefer point reads and parameterized queries over ad hoc string interpolation. For auth, decide early whether you are using a key, DefaultAzureCredential, or ManagedIdentityCredential, because that changes the setup and environment variables.

Practical quality tips

The biggest quality jump usually comes from giving the skill your partition key and your most common query. If those are unclear, the output will be generic and may produce an expensive or awkward container design. Also, specify whether you need single-partition reads, cross-partition search, or point reads, since those choices affect both code and cost.

azure-cosmos-py skill FAQ

Is azure-cosmos-py only for the Azure Cosmos DB Python SDK?

Yes, the azure-cosmos-py skill is centered on the Azure Cosmos DB SDK for Python and the NoSQL API. It is not a general Azure data skill, and it should not be used as a substitute for SQL database guidance or SDKs in other languages.

Do I need the skill if I already know the SDK docs?

If you already know the SDK, the skill is still useful when you need faster setup decisions: what to install, how to authenticate in your environment, and how to structure queries for better performance. It adds a guide layer around the raw API surface.

Is it beginner-friendly?

Yes, if your goal is a small, concrete task like creating a client, reading a document, or setting up a container. It is less friendly if you skip the data-model details, because Cosmos DB decisions depend heavily on partitioning and access patterns.

When should I not use this skill?

Do not use azure-cosmos-py if you are not targeting Cosmos DB NoSQL, if your app is mostly relational, or if you need broad architecture advice rather than Python SDK implementation. It is also not the right choice if you are only looking for a quick code snippet and do not care about partitioning or query cost.

How to Improve azure-cosmos-py skill

Give the partition key and query pattern up front

The highest-value improvement for azure-cosmos-py is to tell it the partition key path and the most common query. That lets it suggest a container design that matches actual access patterns instead of a generic one. If you omit this, you may get code that works but performs poorly.

Be explicit about auth and environment

State whether your target is local development, production, or both. For example, say whether you want DefaultAzureCredential, managed identity, or key-based auth, and include relevant environment variables like COSMOS_ENDPOINT, COSMOS_DATABASE, and COSMOS_CONTAINER. That reduces back-and-forth and produces a more deployable result.

Ask for the exact operation shape

The skill performs better when you request a specific workflow:

• create a container with a partition key
• insert or upsert a document
• read by id and partition key
• run a parameterized query
• compare single-partition and cross-partition options

This is better than asking for “Cosmos examples,” because the SDK guidance changes depending on whether you need point reads, queries, or provisioning.

Iterate using cost and correctness signals

If the first output feels too broad, ask the skill to optimize for one of three things: fewer RUs, simpler code, or safer query handling. For example, request “rewrite this to avoid cross-partition queries” or “convert this string-formatted query into a parameterized one.” Those follow-up prompts usually improve azure-cosmos-py usage more than asking for another general example.