azure-cosmos-db

What this skill does

# 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-L90 | Diagnosing and fixing Cosmos DB issues across APIs (Cassandra, Gremlin, MongoDB, PostgreSQL, SQL), including errors, timeouts, performance, encryption/CMK, connectivity, and SDK/client problems. |
| Best Practices | L91-L154 | Best practices for performance, cost, partitioning, indexing, consistency, SDK usage, change feed, DR/HA, and workload tuning across Cosmos DB APIs (NoSQL, Mongo, Cassandra, PostgreSQL, DocumentDB). |
| Decision Making | L155-L216 | Guidance on choosing Cosmos/DocumentDB/PostgreSQL options (consistency, throughput, regions, pricing), and planning migrations, upgrades, scaling, analytics, and backup/restore strategies. |
| Architecture & Design Patterns | L217-L249 | Architectural patterns for AI/RAG, agent memory, knowledge graphs, multi-tenant and microservice designs, high availability, change feed, analytics, and vector search on Cosmos DB and PostgreSQL. |
| Limits & Quotas | L250-L291 | Limits, quotas, and behaviors for Cosmos DB (and DocumentDB): throughput, autoscale, burst capacity, partitions, backups/restore, serverless, indexing, free tier, and PostgreSQL/Cassandra limits. |
| Security | L292-L363 | Securing Cosmos DB across all APIs: identity/RBAC, network isolation (firewall, Private Link, vnets), encryption/CMK, auditing, data masking, TLS, governance/Policy, and Defender integration. |
| Configuration | L364-L496 | Configuring Cosmos DB and related services: throughput, indexing, backup/restore, monitoring, emulators, vector/search, multi-region, Cassandra/Mongo/PostgreSQL/Table APIs, and SDK performance/observability. |
| Integrations & Coding Patterns | [integrations.md](integrations.md) | SDK patterns, bulk ops, change feed, Kafka/Spark/BI integrations, vector search, RAG/AI patterns, and language-specific samples for Cosmos DB (NoSQL, Mongo, Cassandra, PostgreSQL, Gremlin). |
| Deployment | [deployment.md](deployment.md) | Deploying and managing Cosmos DB (NoSQL, Mongo, Cassandra, PostgreSQL, Table, DocumentDB) with Bicep/ARM/Terraform, CI/CD, emulator, migrations, 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-solutions |
| Resolve common Azure Cosmos DB for MongoDB issues | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/faq |
| Prevent rate-limiting errors in Cosmos DB MongoDB operations | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/prevent-rate-limiting-errors |
| Troubleshoot query performance issues in Cosmos DB MongoDB | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/troubleshoot-query-performance |
| Use aggregated diagnostics logs to troubleshoot Cosmos DB requests | https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-aggregated-logs |
| Troubleshoot Cosmos DB with basic diagnostics KQL queries | https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-logs-basic-queries |
| Monitor normalized request units to diagnose Cosmos DB load | https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-normalized-request-units |
| Analyze Cosmos DB request unit usage for operations | https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-request-unit-usage |
| Monitor and troubleshoot Cosmos DB server-side latency | https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-server-side-latency |
| Troubleshoot connection issues to Azure Cosmos DB for PostgreSQL | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-troubleshoot-common-connection-issues |
| Diagnose and fix read-only Azure Cosmos DB for PostgreSQL clusters | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-troubleshoot-read-only |
| Run useful diagnostic queries on Cosmos DB for PostgreSQL clusters | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-useful-diagnostic-queries |
| Troubleshoot Azure Cosmos DB Shell installation and usage issues | https://learn.microsoft.com/en-us/azure/cosmos-db/shell/troubleshooting |
| Use Azure SRE Agent to diagnose Cosmos DB issues | https://learn.microsoft.com/en-us/azure/cosmos-db/site-reliability-engineering-agent |
| Fix Cosmos DB 400 bad request and partition key errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-bad-request |
| Troubleshoot Azure Functions trigger for Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-changefeed-functions |
| Troubleshoot cross-tenant CMK issues in Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-cmk |
| Resolve Cosmos DB 409 conflict exceptions | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-conflict |
| Troubleshoot Azure Cosmos DB .NET SDK issues | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-dotnet-sdk |
| Resolve Cosmos DB .NET SDK request header too large (400) errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-dotnet-sdk-request-header-too-large |
| Troubleshoot HTTP 4