azure-cosmos-db

# 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-L140 | Performance, scaling, partitioning, RU/cost optimization, SDK usage, change feed, resilience/DR, and best practices for Cosmos DB APIs (NoSQL, MongoDB, Cassandra, PostgreSQL, vector). | | Decision Making | L141-L191 | Guides for choosing Cosmos DB deployment, scaling, consistency, backup, pricing, and migration options across SQL, MongoDB, Cassandra, Table, and PostgreSQL APIs. | | Architecture & Design Patterns | L192-L217 | 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 | L218-L252 | Limits, quotas, and behaviors for Cosmos DB throughput, partitions, backup/restore, serverless, APIs (Cassandra, Gremlin, Table), integrated cache, and PostgreSQL clusters. | | Security | L253-L318 | Securing Cosmos DB: encryption, keys, RBAC/Entra ID, network isolation (VNet, Private Link, firewalls), auditing, data masking, TLS, and security best practices across all APIs. | | Configuration | L319-L445 | Configuring and tuning Azure Cosmos DB and its APIs (NoSQL, Mongo, Cassandra, Gremlin, Table, PostgreSQL): throughput, indexing, backup/restore, monitoring, SDK performance, fleets, emulators, and HA. | | Integrations & Coding Patterns | L446-L572 | SDK patterns, bulk ops, change feed, vector search, Kafka/Spark/Kafka Connect, language-specific samples, and integrations for NoSQL, Cassandra, Mongo, Gremlin, and PostgreSQL APIs. | | Deployment | L573-L598 | Deploying and migrating Cosmos DB (NoSQL, MongoDB, Cassandra, PostgreSQL, Table) using Bicep, ARM, Terraform, CI/CD, emulator, AKS, and handling upgrades, restores, 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 issues for Azure Cosmos DB MongoDB API | 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 408 timeouts in Cosmos DB .NET SDK | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-dotnet-sdk-request-time-out | | Diagnose and fix slow requests in Cosmos DB .NET SDK | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-dotnet-sdk-slow-request | | Troubleshoot Cosmos DB 403 forbidden exceptions | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-forbidden | | Diagnose and troubleshoot Cosmos DB Async Java SDK v2 | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-java-async-sdk | | Troubleshoot HTTP 408 timeouts in Cosmos DB Java v4 SDK | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-java-sdk-request-time-out | | Fix service unavailable errors in Cosmos DB Java v4 SDK | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-java-sdk-service-unavailable | | Troubleshoot Azure Cosmos DB Java SDK v4 issues | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-java-sdk-v4 | | Troubleshoot Cosmos DB 404 Not Found exceptions | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-not-found | | Diagnose and troubleshoot Cosmos DB Python SDK issues | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-python-sdk | | Troubleshoot Azure Cosmos DB SQL query performance issues | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-query-performance | | Troubleshoot Azure Cosmos DB 429 request rate errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-request-rate-too-large | | Resolve Azure Cosmos DB HTTP 408 request timeout errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-request-time-out | | Diagnose SDK availability and failover in multi-region Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-sdk-availability | | Troubleshoot Cosmos DB service unavailable connectivity errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-service-unavailable | | Troubleshoot Cosmos DB 401 unauthorized access errors | https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-unauthorized | | Use Cosmos DB metrics and insights to debug common issues | https://learn.microsoft.com/en-us/azure/cosmos-db/use-metrics | ### Best Practices | Topic | URL | |-------|-----| | Apply automated performance, cost, and security recommendations in Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/automated-recommendations | | Benchmark Cosmos DB for NoSQL with YCSB | https://learn.microsoft.com/en-us/azure/cosmos-db/benchmarking-framework | | Follow best practices for Cosmos DB .NET SDK v3 | https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-dotnet | | Apply Java v4 Cosmos DB SDK best practices | https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-java | | Optimize Azure Cosmos DB with Python SDK best practices | https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-python | | Optimize Azure Cosmos DB with JavaScript SDK best practices | https://learn.microsoft.com/en-us/azure/cosmos-db/best-practices-javascript | | Adapt Apache Cassandra apps to Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/adoption | | Consume change feed from Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/change-feed | | Map Cassandra consistency levels to Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/consistency-mapping | | Apply recommended driver settings for Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/driver-extensions | | Measure RU charges for Cosmos DB Cassandra queries | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/find-request-unit-charge | | Use materialized views (preview) in Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/materialized-views | | Design partitions for Cosmos DB Cassandra workloads | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/partitioning | | Avoid rate limiting with server-side retry in Cosmos DB Cassandra | https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/prevent-rate-limiting-errors | | Implement and consume Azure Cosmos DB change feed | https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed | | Design resilient Cosmos DB SDK client applications | https://learn.microsoft.com/en-us/azure/cosmos-db/conceptual-resilient-sdk-applications | | Understand Cosmos DB conflict types and policies | https://learn.microsoft.com/en-us/azure/cosmos-db/conflict-resolution-policies | | Choose IoT partition keys for Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/design-partitioning-iot | | Apply disaster recovery strategies for Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/disaster-recovery-guidance | | Optimize vector indexing and search in Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/vector-search-performance-tips | | Apply GitHub Copilot best practices for Azure Cosmos DB in VS Code | https://learn.microsoft.com/en-us/azure/cosmos-db/github-copilot-visual-studio-code-best-practices | | Use hierarchical partition keys for scalable Cosmos DB data | https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys | | Enable autoscale throughput for Cosmos DB resources | https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-provision-autoscale-throughput | | Use shared database throughput safely in Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-provision-database-throughput | | Monitor Azure Cosmos DB change feed processor progress | https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-use-change-feed-estimator | | Model and partition real-world data in Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/model-partition-example | | Redistribute throughput across Cosmos DB MongoDB partitions | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/distribute-throughput-across-partitions | | Optimize Cosmos DB for MongoDB indexing configuration | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/indexing | | Optimize write performance for Cosmos DB MongoDB workloads | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/optimize-write-performance | | Optimize Azure Cosmos DB MongoDB workloads post-migration | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/post-migration-optimization | | Use MongoDB read preference with globally distributed Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/readpreference-global-distribution | | Use MongoDB aggregation pipelines on Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/tutorial-aggregation | | Optimize Azure Cosmos DB costs for dev and production workloads | https://learn.microsoft.com/en-us/azure/cosmos-db/optimize-costs | | Use Azure Cosmos DB partial document update effectively | https://learn.microsoft.com/en-us/azure/cosmos-db/partial-document-update-faq | | Choose and manage partition keys in Azure Cosmos DB | https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning | | Optimize performance of Cosmos DB .NET SDK v2 clients | https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips | | Optimize performance of Cosmos DB .NET SDK v3 clients | https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips-dotnet-sdk-v3 | | Apply Cosmos DB SDK query performance best practices | https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips-query-sdk | | Tune query performance in Azure Cosmos DB for PostgreSQL | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/concepts-performance-tuning | | Choose distribution columns in Cosmos DB for PostgreSQL | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-choose-distribution-column | | Optimize pgvector performance in Azure Cosmos DB for PostgreSQL | https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-optimize-performance-pgvector |