azure-cosmos-db

name	azure-cosmos-db
description	Expert knowledge for Azure Cosmos DB development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when using Cosmos DB NoSQL/Mongo/Cassandra APIs, change feed, vector search, global distribution, or HTAP/analytics workloads, and other Azure Cosmos DB related development tasks. Not for Azure Table Storage (use azure-table-storage), Azure SQL Database (use azure-sql-database), Azure Database for MySQL (use azure-database-mysql), Azure Database for PostgreSQL (use azure-database-postgresql).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-04-19","generator":"docs2skills/1.0.0"}

Azure Cosmos DB Skill

This skill provides expert guidance for Azure Cosmos DB. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Location	Description
Troubleshooting	L37-L91	Diagnosing and fixing Cosmos DB issues: SDK errors, timeouts, 4xx/5xx codes, performance/RU analysis, metrics/log queries, CMK/backup problems, and API-specific (Mongo/Cassandra/Gremlin/Postgres) troubleshooting.
Best Practices	L92-L151	Performance, scaling, cost, and resiliency best practices for Cosmos DB (all APIs/SDKs), including partitioning, indexing, throughput, benchmarking, DR, and tuning PostgreSQL/Cassandra workloads
Decision Making	L152-L206	Guides for choosing Cosmos DB options (consistency, throughput, backup, analytics, vector search), estimating RU/costs, and planning/migrating workloads across APIs (Cassandra, MongoDB, PostgreSQL, DynamoDB).
Architecture & Design Patterns	L207-L249	Architectural patterns for Cosmos DB and PostgreSQL: multitenancy, sharding, HA/DR, change feed, HTAP, real-time analytics, and AI/LLM agents, memory, vectors, and semantic caching.
Limits & Quotas	L250-L294	Limits, quotas, and behaviors for Cosmos DB and DocumentDB: RU/throughput, autoscale, burst, backups, partitions, indexing, APIs (Core, Cassandra, Mongo, Table, Gremlin), and PostgreSQL cluster sizing.
Security	L295-L361	Securing Cosmos DB and related services: identity/RBAC, keys and encryption, network isolation (VNet, Private Link, firewalls), TLS, auditing, policies, and data‑level protections.
Configuration	L362-L485	Configuring Cosmos DB and related services: throughput, indexing, TTL, backup/restore, global distribution, monitoring, emulators, SDK tuning, and deployment via Bicep/ARM/Terraform across all APIs.
Integrations & Coding Patterns	integrations.md	SDK patterns, bulk ops, change feed, vector search, and integrations (Kafka, Spark, Functions, BI, AI agents) for Cosmos DB APIs (NoSQL, Mongo, Cassandra, PostgreSQL, Gremlin, DocumentDB).
Deployment	deployment.md	Deploying and managing Cosmos DB and Azure DocumentDB: ARM/Bicep/Terraform templates, CI/CD, scaling, backup/restore, upgrades, maintenance, and start/stop operations for various APIs.

Troubleshooting

Topic	URL
Run diagnostic log queries for Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/diagnostic-queries
Use Log Analytics to diagnose Cosmos DB Cassandra server errors	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/error-codes-solution
FAQ and troubleshooting for Cassandra API materialized views	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/materialized-views-faq
Troubleshoot common Cosmos DB Cassandra API errors	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/troubleshoot-common-issues
Resolve NoHostAvailableException and NoNodeAvailableException in Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/troubleshoot-nohostavailable-exception
Troubleshoot revoked-state Cosmos DB CMK accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/cmk-troubleshooting-guide
Use advanced diagnostics queries to troubleshoot Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/diagnostic-queries
Query diagnostics logs for Cosmos DB Gremlin issues	https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/diagnostic-queries
Use diagnostics queries to troubleshoot Cosmos DB MongoDB	https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/diagnostic-queries
Troubleshoot common Cosmos DB MongoDB errors	https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/error-codes-solutions
Prevent rate-limiting errors in Cosmos DB MongoDB	https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/prevent-rate-limiting-errors

Best Practices

Topic	URL
Apply automated performance and cost recommendations in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/automated-recommendations
Benchmark Azure Cosmos DB for NoSQL with YCSB	https://learn.microsoft.com/en-us/azure/cosmos-db/benchmarking-framework
Best practices for Azure Cosmos DB .NET SDK v3	https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-dotnet
Best practices for Azure Cosmos DB Java SDK v4	https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-java
Optimize Azure Cosmos DB Python SDK performance	https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-python
Apply performance best practices for Cosmos DB JavaScript SDK	https://learn.microsoft.com/en-us/azure/cosmos-db/best-practices-javascript
Adapt Apache Cassandra applications to Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/adoption
Apply recommended Cosmos DB Cassandra driver extension settings	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/driver-extensions
Implement lightweight transactions in Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/lightweight-transactions
Use materialized views in Cosmos DB Cassandra API (preview)	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/materialized-views
Avoid rate-limiting errors with server-side retries in Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/prevent-rate-limiting-errors

Decision Making

Topic	URL
Choose analytics and BI options for Cosmos DB data	https://learn.microsoft.com/en-us/azure/cosmos-db/analytics-and-business-intelligence-overview
Apply Cosmos DB near real-time analytics to key use cases	https://learn.microsoft.com/en-us/azure/cosmos-db/analytics-and-business-intelligence-use-cases
Map Cassandra consistency levels to Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/consistency-mapping
Migrate on-premises Cassandra data to Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data
Migrate Apache Cassandra data to Cosmos DB Cassandra using Databricks	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data-databricks
Live-migrate Apache Cassandra to Cosmos DB Cassandra with dual-write	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data-dual-write-proxy
Choose scaling options for Cosmos DB Cassandra accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/scale-account-throughput
Select appropriate change feed mode for Cosmos DB workloads	https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-modes
Choose appropriate consistency levels in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels
Estimate Cosmos DB RU/s from existing vCores	https://learn.microsoft.com/en-us/azure/cosmos-db/convert-vcore-to-request-unit
Decide when to use Azure Cosmos DB dedicated gateway	https://learn.microsoft.com/en-us/azure/cosmos-db/dedicated-gateway

Architecture & Design Patterns

Topic	URL
Implement AI agents and memory solutions with Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/ai-agents
Understand and use Cosmos DB analytical store	https://learn.microsoft.com/en-us/azure/cosmos-db/analytical-store-introduction
Choose Cosmos DB change feed design patterns and trade-offs	https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-design-patterns
Use Cosmos DB change feed for real-time e-commerce analytics	https://learn.microsoft.com/en-us/azure/cosmos-db/changefeed-ecommerce-solution
Design multitenant applications with Azure Cosmos DB fleets	https://learn.microsoft.com/en-us/azure/cosmos-db/fleet
Design agent memory patterns using Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/agentic-memories
Model AI knowledge graphs on Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/cosmos-ai-graph
Design semantic cache for LLMs using Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/semantic-cache
Architect multitenant generative AI apps on Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/multi-tenancy-vector-search
Design for AZ outage resiliency in Cosmos DB PostgreSQL	https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/concepts-availability-zones
Design colocated tables in Azure Cosmos DB for PostgreSQL	https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/concepts-colocation

Limits & Quotas

Topic	URL
Autoscale throughput limits and behaviors in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/autoscale-faq
Use burst capacity and understand RU limits in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/burst-capacity
FAQ on Cosmos DB burst capacity limits and behavior	https://learn.microsoft.com/en-us/azure/cosmos-db/burst-capacity-faq
Review FAQs and limits for Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/faq
Azure Cosmos DB service quotas and default limits	https://learn.microsoft.com/en-us/azure/cosmos-db/concepts-limits
FAQ on Cosmos DB continuous backup and PITR limits	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-frequently-asked-questions
Understand limits and pricing for Cosmos DB continuous backup	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-introduction
FAQ on Cosmos DB throughput redistribution limits	https://learn.microsoft.com/en-us/azure/cosmos-db/distribute-throughput-across-partitions-faq
FAQ on Azure Cosmos DB fleets, fleetspaces, and accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/fleet-faq
Use Cosmos DB lifetime free tier limits effectively	https://learn.microsoft.com/en-us/azure/cosmos-db/free-tier
Understand and use Cosmos DB global secondary indexes (preview)	https://learn.microsoft.com/en-us/azure/cosmos-db/global-secondary-indexes
Runtime limits for Cosmos DB Gremlin engine

Security

Topic	URL
Use managed identity for Cosmos DB access to Key Vault	https://learn.microsoft.com/en-us/azure/cosmos-db/access-key-vault-managed-identity
Configure private endpoints for Cosmos DB analytical store	https://learn.microsoft.com/en-us/azure/cosmos-db/analytical-store-private-endpoints
Audit Cosmos DB control plane operations with logs	https://learn.microsoft.com/en-us/azure/cosmos-db/audit-control-plane-logs
Configure RBAC permissions for Cosmos DB continuous backup restore	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-permissions
Configure Cosmos DB to meet data residency requirements	https://learn.microsoft.com/en-us/azure/cosmos-db/data-residency
Use Microsoft Defender threat protection for Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/defender-for-cosmos-db
Configure Dynamic Data Masking in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/dynamic-data-masking
Secure Azure Cosmos DB for Gremlin accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/security
Add and assign Cosmos DB RBAC user roles	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-add-assign-user-roles
Use Always Encrypted client-side encryption in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-always-encrypted
Configure CORS settings for Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-configure-cross-origin-resource-sharing

Configuration

Topic	URL
Audit Cosmos DB point-in-time restore operations	https://learn.microsoft.com/en-us/azure/cosmos-db/audit-restore-continuous
Deploy and configure Azure Cosmos DB with Bicep	https://learn.microsoft.com/en-us/azure/cosmos-db/bicep-samples
Retrieve RU charge for Cassandra API queries	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/find-request-unit-charge
Configure provisioned and autoscale throughput for Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/how-to-provision-throughput
Deploy and configure Cassandra API accounts with Bicep	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/manage-with-bicep
Configure monitoring and insights for Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/monitor-insights
Use tokens and token() function in Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/tokens
Change the partition key of a Cosmos DB container	https://learn.microsoft.com/en-us/azure/cosmos-db/change-partition-key
Configure and run Synapse Link on Cosmos DB accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/configure-synapse-link
Configure and run Azure Cosmos DB container copy jobs	https://learn.microsoft.com/en-us/azure/cosmos-db/container-copy
Understand Cosmos DB resource model for point-in-time restore	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-resource-model