/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 SQL/Mongo/Cassandra APIs, change feed, multi-region HA, vector search, or Cosmos DB for PostgreSQL, and other Azure Cosmos DB related development tasks. Not for Azure DocumentDB (use azure-documentdb), Azure Table Storage (use azure-table-storage), Azure SQL Database (use azure-sql-database), Azure Blob Storage (use azure-blob-storage).
compatibility: Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata:
  generated_at: "2026-11-08"
  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 | Location | Description | |----------|----------|-------------| | Troubleshooting | L37-L87 | Diagnosing and fixing Cosmos DB issues: API-specific errors (Cassandra, Gremlin, MongoDB, PostgreSQL), SDK timeouts/403/404/429, CMK/connection problems, and KQL/log-based performance troubleshooting. | | Best Practices | L88-L141 | Performance, cost, partitioning, and resilience best practices for Cosmos DB (NoSQL, Mongo, Cassandra, PostgreSQL), including SDK tuning, RU optimization, change feed, autoscale, and vector search. | | Decision Making | L142-L192 | Guides for choosing Cosmos DB deployment, scaling, consistency, backup, pricing, and migration options across SQL, MongoDB, Cassandra, Table, and PostgreSQL APIs. | | Architecture & Design Patterns | L193-L218 | 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 | L219-L253 | Limits, quotas, and behaviors for Cosmos DB throughput, partitions, backup/restore, serverless, APIs (Cassandra, Gremlin, Table), integrated cache, and PostgreSQL clusters. | | Security | L254-L320 | Securing Cosmos DB across APIs: identity/RBAC, keys & encryption, network isolation (VNet, Private Link, firewalls), TLS, auditing, data masking, policy/governance, and best‑practice hardening. | | Configuration | L321-L449 | Configuring and tuning Cosmos DB and Cosmos DB for PostgreSQL: throughput, indexing, backup/restore, consistency, monitoring, SDK performance, emulators, fleets, and feature support per API. | | Integrations & Coding Patterns | [integrations.md](integrations.md) | SDK patterns, bulk ops, change feed, vector search, Kafka/Spark/Kafka Connect, and language-specific samples for integrating apps and tools with all Azure Cosmos DB APIs. | | Deployment | [deployment.md](deployment.md) | Deploying and managing Cosmos DB (NoSQL, Cassandra, MongoDB, PostgreSQL, Table) with Bicep/ARM/Terraform, app deployments, bulk import/migration, restores, upgrades, and maintenance. |

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-soluti