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 building Cosmos DB NoSQL/Mongo/Cassandra apps, using change feed, multi-region, vector search, or AI/RAG, 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 Data Explorer (use azure-data-explorer). Use when this capability is needed.
metadata	{"author":"gabrielmoreira"}

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

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
Use Python Cosmos DB SDK with best practices	https://learn.microsoft.com/en-us/azure/cosmos-db/best-practice-python
Apply JavaScript Cosmos DB 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
Configure Cosmos DB Cassandra extension driver settings	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 lightweight transactions 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 throughput	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 Cosmos DB RU/s and cost with capacity planner	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
Design RAG architectures with Cosmos DB vector search	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/rag
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

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
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
Use Cosmos DB continuous backup and point-in-time restore	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
Reference Azure Cosmos DB service limits and quotas	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	https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/stopwords
Review runtime limits for Cosmos DB Gremlin engine

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

---

Source: gabrielmoreira/agent-skills-mirror — distributed by TomeVault.