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

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

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

Decision Making

Topic	URL
Choose analytics and BI options for Azure Cosmos DB data	https://learn.microsoft.com/en-us/azure/cosmos-db/analytics-and-business-intelligence-overview
Live dual-write migration to Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data-dual-write-proxy
Choose scaling options for Cosmos DB Cassandra API	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/scale-account-throughput
Choose Azure Cosmos DB consistency levels	https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels
Convert vCores to Cosmos DB RU/s for migration	https://learn.microsoft.com/en-us/azure/cosmos-db/convert-vcore-to-request-unit
Decide when to use Cosmos DB dedicated gateway	https://learn.microsoft.com/en-us/azure/cosmos-db/dedicated-gateway
Estimate Azure Cosmos DB RU/s and costs	https://learn.microsoft.com/en-us/azure/cosmos-db/estimate-ru-with-capacity-planner
Manage multitenant throughput with Cosmos DB fleet pools	https://learn.microsoft.com/en-us/azure/cosmos-db/fleet-pools
Use global secondary indexes in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/global-secondary-indexes
Choose Cosmos DB manual vs autoscale throughput	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-choose-offer
Migrate from Cosmos DB .NET bulk executor to SDK v3 bulk support	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-migrate-from-bulk-executor-library

Architecture & Design Patterns

Topic	URL
Implement AI agents and memory on Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/ai-agents
Design bulk import and update patterns with Cosmos DB bulk executor	https://learn.microsoft.com/en-us/azure/cosmos-db/bulk-executor-overview
Apply Azure Cosmos DB change feed design patterns	https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-design-patterns
Use Cosmos DB change feed for real-time analytics	https://learn.microsoft.com/en-us/azure/cosmos-db/changefeed-ecommerce-solution
Design agent memory patterns with Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/agentic-memories
Design AI knowledge graphs with Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/cosmos-ai-graph
Supply chain traceability solution with Cosmos DB Gremlin	https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/solution-supply-chain-traceability
Configure multiple Azure Functions triggers for Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-create-multiple-cosmos-db-triggers
Design Azure Cosmos DB multi-region write strategies	https://learn.microsoft.com/en-us/azure/cosmos-db/multi-region-writes
Apply per-partition automatic failover in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/per-partition-automatic-failover
Plan availability zone outage resiliency for Cosmos DB for PostgreSQL	https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/concepts-availability-zones

Limits & Quotas

Topic	URL
Autoscale throughput limits and behavior in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/autoscale-faq
Use Cosmos DB burst capacity limits effectively	https://learn.microsoft.com/en-us/azure/cosmos-db/burst-capacity
Burst capacity limits and usage rules in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/burst-capacity-faq
Use lightweight transactions in Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/lightweight-transactions
Choose Azure Cosmos DB change feed modes and limits	https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-modes
Azure Cosmos DB service quotas and default limits reference	https://learn.microsoft.com/en-us/azure/cosmos-db/concepts-limits
Understand limits for Cosmos DB continuous backup restore	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-frequently-asked-questions
Understand Azure Cosmos DB continuous backup limits	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-introduction
Throughput redistribution limits across Cosmos DB partitions	https://learn.microsoft.com/en-us/azure/cosmos-db/distribute-throughput-across-partitions-faq
Azure Cosmos DB service limits and behaviors FAQ	https://learn.microsoft.com/en-us/azure/cosmos-db/faq
Use Cosmos DB lifetime free tier limits	https://learn.microsoft.com/en-us/azure/cosmos-db/free-tier
Reference stopwords for Cosmos DB full text search

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
Secure Azure Cosmos DB for Apache Cassandra accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/security
Configure RBAC permissions for Cosmos DB continuous 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
Understand encryption at rest in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/database-encryption-at-rest
Protect Cosmos DB with Microsoft Defender for Cloud	https://learn.microsoft.com/en-us/azure/cosmos-db/defender-for-cosmos-db
Configure Dynamic Data Masking in Azure Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/dynamic-data-masking
Configure security for Azure Cosmos DB Gremlin accounts	https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/security
Add and assign RBAC user roles in Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-add-assign-user-roles

Configuration

Topic	URL
Configure change data capture for Cosmos DB analytical store	https://learn.microsoft.com/en-us/azure/cosmos-db/analytical-store-change-data-capture
Audit Cosmos DB point-in-time restore operations via activity logs	https://learn.microsoft.com/en-us/azure/cosmos-db/audit-restore-continuous
Create Cosmos DB Cassandra containers via portal and SDKs	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/how-to-create-container
Configure provisioned and autoscale throughput for Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/how-to-provision-throughput
Configure monitoring insights for Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/monitor-insights
Reconfigure Azure Cosmos DB container partition key	https://learn.microsoft.com/en-us/azure/cosmos-db/change-partition-key
Configure and manage Azure Cosmos DB container copy jobs	https://learn.microsoft.com/en-us/azure/cosmos-db/container-copy
Configure resource model for Cosmos DB point-in-time restore	https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-resource-model
Configure Azure Monitor alerts for Cosmos DB metrics and logs	https://learn.microsoft.com/en-us/azure/cosmos-db/create-alerts
Configure and use the Cosmos DB local emulator	https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
Configure and run Azure Cosmos DB Linux-based emulator	https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux

Integrations & Coding Patterns

Topic	URL
Use Azure CLI samples for Cosmos DB Cassandra management	https://github.com/azure-samples/azure-cli-samples/tree/master/cosmosdb/cassandra
Use PowerShell samples to manage Cosmos DB Cassandra resources	https://github.com/azure/azure-docs-powershell-samples/tree/master/cosmosdb/cassandra
Use .NET bulk executor library for Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/bulk-executor-dotnet
Implement bulk import with Azure Cosmos DB Java SDK	https://learn.microsoft.com/en-us/azure/cosmos-db/bulk-executor-java
Configure Spark integration with Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/connect-spark-configuration
Run Glowroot APM with Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/glowroot
Configure Kafka Connect to Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/kafka-connect
Migrate Cassandra data via Databricks to Cosmos DB	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data-databricks
Migrate Oracle to Cosmos DB Cassandra using Arcion	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/oracle-migrate-cosmos-db-arcion
Sync PostgreSQL to Cosmos DB Cassandra using Kafka	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/postgres-migrate-cosmos-db-kafka
Run Spark aggregation queries on Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/spark-aggregation-operations

Deployment

Topic	URL
Deploy Cosmos DB NoSQL resources using Bicep	https://learn.microsoft.com/en-us/azure/cosmos-db/bicep-samples
Manage Cosmos DB Cassandra with Bicep templates	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/manage-with-bicep
Migrate Apache Cassandra data to Cosmos DB Cassandra	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data
Migrate Oracle data to Cosmos DB Cassandra with Striim	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/migrate-data-striim
Deploy Cosmos DB Cassandra resources with ARM templates	https://learn.microsoft.com/en-us/azure/cosmos-db/cassandra/templates-samples
Deploy Cosmos DB web app using ARM template	https://learn.microsoft.com/en-us/azure/cosmos-db/create-website
Use Cosmos DB emulator for local development and CI	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-develop-emulator
Restore deleted Cosmos DB containers or databases in-account	https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-restore-in-account-continuous-backup
Deploy Azure Cosmos DB resources with ARM templates	https://learn.microsoft.com/en-us/azure/cosmos-db/manage-with-templates
Manage Cosmos DB for MongoDB using Bicep	https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/manage-with-bicep
Migrate large MongoDB datasets to Cosmos DB with Databricks	https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/migrate-databricks