/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 APIs (NoSQL/Mongo/Cassandra/PostgreSQL), change feed, vector search, Kafka/Spark, or multi-region HA, 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 HDInsight (use azure-hdinsight).
compatibility: Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata:
  generated_at: "2026-08-09"
  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](https://github.com/MicrosoftDocs/mcp/blob/main/README.md)

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 | Lines | Description | |----------|-------|-------------| | Troubleshooting | L37-L87 | Diagnosing and fixing Cosmos DB issues across APIs and SDKs: connection and timeout errors, RU/latency problems, encryption/CMK and replication issues, and advanced diagnostics/log queries. | | Best Practices | L88-L141 | Best practices for performance, cost, partitioning, consistency, SDK usage, change feed, disaster recovery, and workload tuning across Cosmos DB APIs (NoSQL, MongoDB, Cassandra, PostgreSQL). | | Decision Making | L142-L188 | Guides for choosing Cosmos DB deployment, scaling, consistency, pricing, migration, SDK upgrades, and PostgreSQL/Mongo/Cassandra/Table options to match workload, cost, and resiliency needs. | | Architecture & Design Patterns | L189-L216 | Patterns and reference architectures for AI agents, change feed, analytics, multi-region HA, SaaS/multi-tenant design, microservices, and vector/AI search on Cosmos DB and Cosmos DB for PostgreSQL. | | Limits & Quotas | L217-L251 | Limits, quotas, and behaviors for Cosmos DB throughput, partitions, backups, serverless, APIs (Core, Cassandra, Gremlin, Table, PostgreSQL), and related performance/retention constraints. | | Security | L252-L318 | Securing Cosmos DB and related services: identity/RBAC, network isolation (firewall, Private Link, VNet), encryption/CMK, auditing, data masking, TLS, and security best practices per API. | | Configuration | L319-L441 | Configuring Cosmos DB and its APIs: throughput, indexing, backup/restore, fleets, emulators, monitoring, alerts, SDK tuning, and PostgreSQL/Cassandra/MongoDB-specific settings. | | Integrations & Coding Patterns | L442-L568 | SDK usage, integrations, and patterns for connecting apps/tools to Cosmos DB (NoSQL, Mongo, Cassandra, PostgreSQL), including change feed, Kafka/Spark, vector search, and bulk/transactional operations. | | Deployment | L569-L596 | Deploying, migrating, and managing Cosmos DB (NoSQL, Cassandra, MongoDB, PostgreSQL, Table) using Bicep/ARM/Terraform, CI/CD, emulator, AKS apps, and bulk import workflows. |

Troubleshooting

| Topic | URL | |-------|-----| | Run advanced diagnostics queries for Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/diagnostic-queries | | Use Log Analytics for Cosmos DB Cassandra error codes | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/error-codes-solution | | Resolve issues with Cassandra materialized views in Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/materialized-views-faq | | Resolve common Cosmos DB Cassandra API errors | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/troubleshoot-common-issues | | Fix NoHostAvailable and NoNodeAvailable 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 | | Troubleshoot Cosmos DB with advanced diagnostics log queries | https://learn.microsoft.com/en-us/azure/cosmos-db/diagnostic-queries | | Run advanced diagnostics queries for Cosmos DB Gremlin | https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/diagnostic-queries | | Troubleshoot common questions for Azure Cosmos DB Gremlin API | https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/faq | | Interpret Cosmos DB Gremlin response headers for debugging | https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/headers | | Use diagnostics queries to troubleshoot Cosmos DB MongoDB | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/diagnostic-queries | | Resolve common Azure Cosmos DB MongoDB error codes | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/error-codes-solutions | | Res