What This Skill Does
The Azure Cosmos DB Python SDK skill provides AI agents with comprehensive document database capabilities through Microsoft's globally distributed NoSQL platform. This skill enables agents to store, retrieve, query, and manage JSON documents with automatic indexing, partition-based scaling, and multi-region replication without managing database infrastructure.
Unlike traditional SQL databases requiring rigid schemas, Cosmos DB's document model accommodates flexible data structures that evolve over time. Agents can store heterogeneous documents in the same container while automatic indexing ensures fast queries without manual index management. The Python SDK exposes these capabilities through clean, Pythonic interfaces supporting both synchronous and asynchronous programming patterns.
The skill handles critical distributed database concerns transparently including partition routing for efficient queries, request unit tracking for cost management, and connection pooling for optimal performance. Agents build applications that scale globally while the SDK manages complexity like regional failover, retry logic for transient failures, and optimal request routing across Cosmos DB's distributed architecture.
Getting Started
Create an Azure Cosmos DB account through the Azure portal, selecting the NoSQL API to work with this SDK. Note your endpoint URL and configure authentication credentials, preferably using DefaultAzureCredential for production deployments or account keys for development simplicity.
Install the azure-cosmos package along with azure-identity for credential management. The SDK requires no additional configuration files or complex setup beyond importing the client classes and initializing with your endpoint and credentials.
Environment variables store configuration like endpoint URLs, database names, and container IDs. This approach enables the same code to run across development, testing, and production environments by changing configuration without modifying application logic.
Understanding the client hierarchy helps navigate operations effectively. CosmosClient provides account-level functionality, DatabaseProxy handles database operations like container management, and ContainerProxy executes item CRUD operations and queries. This structure maps directly to Cosmos DB's resource organization.
Key Features
Document CRUD Operations — Create, read, update, and delete JSON documents with simple method calls. The SDK automatically serializes Python dictionaries to JSON and deserializes results back to native types. Operations require item IDs and partition key values for efficient routing to specific partitions.
Flexible Querying — Execute SQL-like queries using familiar syntax without complex query builders. Parameterized queries prevent injection attacks and improve query plan caching. The SDK handles result pagination automatically, streaming large result sets efficiently without loading everything into memory.
Partition Key Management — Cosmos DB distributes data across partitions based on partition key values for horizontal scaling. The SDK enforces partition key specification for operations, ensuring queries remain efficient by targeting specific partitions rather than scanning the entire container.
Hierarchical Partition Keys — Advanced scenarios support multi-level partition keys creating nested data hierarchies. This enables efficient querying along multiple dimensions while maintaining even data distribution across partitions.
Upsert Semantics — Combine create and update logic into single operations that insert new documents or replace existing ones atomically. This simplifies idempotent operation patterns and reduces code complexity for applications handling uncertain document existence.
Throughput Management — Provision and monitor request units per second at container or database level. Query current throughput settings, update capacity dynamically based on demand, and track request unit consumption per operation for cost optimization.
Async Support — The async client variant enables high-concurrency applications using Python's asyncio framework. Context managers ensure proper resource cleanup while async iterators stream query results without blocking the event loop.
Usage Examples
Database and container creation uses idempotent methods that succeed whether resources exist or not. Specify partition key paths during container creation since they can't be changed later. These setup operations typically run during application initialization or deployment.
Creating items inserts JSON documents into containers with automatic partition placement based on partition key values. The SDK validates that documents include partition key fields and returns created documents with system-generated properties like timestamps and ETags.
Reading specific items requires both the document ID and partition key value, enabling single-digit millisecond latency through direct partition routing. This differs from queries which may need to scan multiple documents but remains the most efficient retrieval method for known documents.
Querying uses SQL syntax familiar to developers from relational databases while accommodating JSON's hierarchical structure. Parameterized queries separate data from query logic for security and performance. Including partition keys in WHERE clauses keeps queries efficient by limiting scans to relevant partitions.
Cross-partition queries scan the entire container when partition keys aren't specified in filters. While supported, these operations consume more request units and exhibit higher latency than partition-scoped queries. Reserve cross-partition queries for scenarios where data patterns genuinely require scanning multiple partitions.
Updating documents follows a retrieve-modify-replace pattern where you read the current document, update desired fields in memory, and write the modified version back. This ensures updates operate on latest data and provides opportunities for validation or conditional updates based on document state.
Best Practices
Always specify partition keys for item operations and queries whenever possible. Operations targeting specific partitions execute orders of magnitude faster than cross-partition scans and consume fewer request units. Design data models where most access patterns align with partition key values.
Use parameterized queries exclusively rather than string concatenation or interpolation. Parameterization prevents SQL injection vulnerabilities, enables query plan caching for better performance, and separates data from query structure for cleaner code.
Prefer upsert_item over conditional create/update logic when document existence is uncertain. Upserts simplify code by handling both cases atomically while reducing round trips compared to checking existence separately before deciding create versus update.
Use the async client for applications handling many concurrent database operations. Async patterns prevent thread exhaustion and enable higher throughput compared to synchronous blocking calls. Sync clients suit simpler scripts or applications with minimal concurrency.
Design partition keys for high cardinality with many unique values to distribute data evenly across partitions. Avoid low-cardinality keys that concentrate data in few partitions creating hot spots. Good partition keys appear in most query filters while distributing load uniformly.
Monitor request unit consumption patterns to optimize costs and performance. High RU charges indicate opportunities for query optimization, indexing policy adjustments, or partition key redesign. Right-size provisioned throughput based on actual usage patterns rather than guessing.
Handle CosmosHttpResponseError exceptions explicitly for expected conditions like missing documents or rate limiting. Status code 404 indicates not found, 429 indicates throttling, and 409 indicates conflicts. Let unexpected errors propagate for proper error tracking.
When to Use This Skill
Use this skill for applications requiring flexible schema storage where document structures evolve over time. User profiles, product catalogs, content management, and IoT telemetry often have varying attributes that benefit from document databases rather than rigid schemas.
Global applications serving users across multiple regions leverage Cosmos DB's multi-region replication with local read replicas. The SDK automatically routes requests to optimal regions for lowest latency while maintaining consistency guarantees across regions.
High-scale transactional workloads requiring elastic throughput scaling benefit from Cosmos DB's partition-based architecture. Mobile backends, gaming services, and e-commerce platforms scale horizontally by adding partitions as data and throughput requirements grow.
Python applications built with FastAPI, Flask, or async frameworks integrate naturally with the SDK's sync and async clients. Modern cloud-native applications benefit from Cosmos DB's serverless deployment options and consumption-based pricing.
When NOT to Use This Skill
Avoid Cosmos DB for workloads requiring complex multi-document transactions or joins across documents. While Cosmos DB supports transactions within partitions, cross-partition transactions aren't available. Relational databases better serve normalized data with intricate relationships.
Don't use Cosmos DB for primarily analytical workloads involving aggregations, full table scans, or data warehouse patterns. Specialized analytics databases with columnar storage optimize for such patterns. Cosmos DB excels at transactional workloads with partition-scoped queries.
Skip Cosmos DB when working with append-only time-series data better suited to Azure Data Explorer or specialized time-series databases. While Cosmos can store such data, purpose-built solutions provide better compression, query performance, and cost efficiency.
Avoid Cosmos DB if budget constraints prohibit paying for provisioned throughput or your workload fits entirely within single-server database capacity. Traditional databases may prove more cost-effective for small-scale applications despite operational overhead.
Related Skills
Explore azure-cosmos-db-py for production-grade service layer patterns, TDD practices, and architectural guidance building on this SDK.
Check azure-identity-py for authentication patterns integrating with Cosmos DB, especially DefaultAzureCredential and managed identities.
Consider azure-functions-py for building serverless applications triggered by Cosmos DB change feed, enabling event-driven architectures.
Source
Provider: Microsoft
Category: Cloud & Azure
Package: azure-cosmos
Official Documentation: Azure Cosmos DB SDK for Python