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/PostgreSQL APIs, change feed, vector search, global distribution, or HTAP 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 SQL Managed Instance (use azure-sql-managed-instance), Azure Blob Storage (use azure-blob-storage). Use when this capability is needed.
metadata	{"author":"atc-net"}

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: This file may be large. Use the Category Index below to locate relevant sections, then use read_file with specific line ranges (e.g., L136-L144) to read the sections needed for the user's question This skill requires network access to fetch documentation content. Use mcp_microsoftdocs:microsoft_docs_fetch to retrieve full articles.

• Fallback: Use the built-in WebFetch tool if the Microsoft Learn MCP server is not available.

Category Index

Category	Lines	Description
Troubleshooting	L31-L83	Diagnosing and fixing Cosmos DB issues across APIs and SDKs: errors (400–503, 401/403/404/409/429), timeouts, performance, connectivity, CMK/backup, and using metrics/logs for root-cause analysis.
Best Practices	L85-L143	Performance, scaling, partitioning, indexing, cost optimization, SDK usage, and HA/DR best practices for Cosmos DB (NoSQL, MongoDB, Cassandra, PostgreSQL) and legacy DocumentDB.
Decision Making	L145-L199	Guides for choosing Cosmos DB options (consistency, throughput, backup, analytics, vector search), estimating cost/RUs, and planning/migrating workloads across APIs (Core, Mongo, Cassandra, PostgreSQL).
Architecture & Design Patterns	L201-L242	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	L244-L282	Limits, quotas, and behaviors for Cosmos DB (all APIs, backup modes, autoscale, serverless, free tier), plus PostgreSQL/Cassandra/Table/MongoDB constraints, RUs, partitions, and capacity usage.
Security	L284-L349	Securing Cosmos DB and related services: identity/RBAC, keys and encryption, network isolation (VNet, firewalls, Private Link), TLS, auditing, policies, and Defender-based threat protection.
Configuration	L351-L477	Configuring and deploying Cosmos DB (all APIs) and DocumentDB: throughput, indexing, TTL, backup/restore, global distribution, search/vector, emulators, monitoring, and infrastructure-as-code.
Integrations & Coding Patterns	references/integrations.md	SDK patterns, change feed, vector search, and integration guides for Cosmos DB across APIs (NoSQL, Mongo, Cassandra, PostgreSQL, Gremlin, DocumentDB) plus Kafka, Spark, BI, and migration tools.
Deployment	references/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
Best practices for Azure Cosmos DB Python SDK	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
Evaluate Cassandra feature support in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/support
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

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

---

Source: atc-net/atc-agentic-toolkit — distributed by TomeVault.