cosmosdb-best-practices

by microsoft

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 75+ rules across 11 categories, prioritized by impact to guide automated refactoring and code generation.

npx skills add https://github.com/microsoft/vscode-cosmosdb --skill cosmosdb-best-practices
Download ZIPGitHub
199

Azure Cosmos DB Best Practices

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 100+ rules across 12 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

  • Designing data models for Cosmos DB
  • Choosing partition keys
  • Writing or optimizing queries
  • Implementing SDK patterns
  • Using the Cosmos DB Emulator for local development
  • Inspecting or managing Cosmos DB data with developer tooling
  • Implementing vector search or RAG features on Cosmos DB
  • Reviewing code for performance issues
  • Configuring throughput and scaling
  • Building globally distributed applications

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Data ModelingCRITICALmodel-
2Partition Key DesignCRITICALpartition-
3Query OptimizationHIGHquery-
4SDK Best PracticesHIGHsdk-
5Indexing StrategiesMEDIUM-HIGHindex-
6Throughput & ScalingMEDIUMthroughput-
7Global DistributionMEDIUMglobal-
8Monitoring & DiagnosticsLOW-MEDIUMmonitoring-
9Design PatternsHIGHpattern-
10Developer ToolingMEDIUMtooling-
11Vector SearchHIGHvector-

Quick Reference

1. Data Modeling (CRITICAL)

2. Partition Key Design (CRITICAL)

3. Query Optimization (HIGH)

4. SDK Best Practices (HIGH)

5. Indexing Strategies (MEDIUM-HIGH)

6. Throughput & Scaling (MEDIUM)

7. Global Distribution (MEDIUM)

8. Monitoring & Diagnostics (LOW-MEDIUM)

9. Design Patterns (HIGH)

10. Developer Tooling (MEDIUM)

11. Vector Search (HIGH)

12. Full-Text Search (HIGH)

  • fts-enable-capability - Enable EnableNoSQLFullTextSearch capability on the account — prerequisite for all FTS functions
  • fts-full-text-policy - Define fullTextPolicy on the container with correct language code (en-US, case-sensitive)
  • fts-index-policy - Add fullTextIndexes entry in the indexing policy to build the inverted index
  • fts-contains-query - Use FullTextContains / FullTextContainsAll / FullTextContainsAny instead of CONTAINS(LOWER(...))
  • fts-score-ranking - Use ORDER BY RANK FullTextScore(path, term) for BM25 relevance ranking
  • fts-hybrid-query - Combine FTS predicates with range/equality filters; put most selective filter first

How to Use

Use the linked rule files above for detailed explanations and code examples. The links give the agent direct paths to the relevant guidance instead of relying on folder scanning or inferred filenames.

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references

More skills from microsoft

oss-growth
microsoft
OSS growth hacker persona
agent-framework-azure-ai-py
microsoft
Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code interpreter, file search, web search), integrating MCP servers, managing conversation threads, or implementing streaming responses. Covers function tools, structured outputs, and multi-tool agents.
development
airunway-aks-setup
microsoft
Set up AI Runway on AKS — from bare cluster to running model. Covers cluster verification, controller install, GPU assessment, provider setup, and first deployment. WHEN: "setup AI Runway", "onboard AKS cluster", "install AI Runway", "airunway setup", "deploy model to AKS", "GPU inference on AKS", "KAITO setup on AKS", "run LLM on AKS", "vLLM on AKS", "set up model serving on AKS", "AI Runway controller".
devops
appinsights-instrumentation
microsoft
Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.
devops
applicationinsights-web-ts
microsoft
Instrument browser/web apps with the Application Insights JavaScript SDK (@microsoft/applicationinsights-web). Use for Real User Monitoring (RUM) — page views, clicks, AJAX/fetch dependencies, exceptions, custom events, and browser-side GenAI agent traces correlated to backend OpenTelemetry traces. Covers SDK Loader Script and npm setup, framework extensions (React, React Native, Angular), Click Analytics, telemetry initializers, and OTel GenAI semantic conventions for agent/tool/model spans emitted from the browser.
devops
azure-ai-anomalydetector-java
microsoft
Build anomaly detection applications with Azure AI Anomaly Detector SDK for Java. Use when implementing univariate/multivariate anomaly detection, time-series analysis, or AI-powered monitoring.
development
azure-ai-language-conversations-py
microsoft
Implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations Python SDK. Use when working with ConversationAnalysisClient to analyze conversation intent and entities, building NLP features, or integrating language understanding into applications.
development
azure-ai-ml-py
microsoft
Azure Machine Learning SDK v2 for Python. Use for ML workspaces, jobs, models, datasets, compute, and pipelines. Triggers: "azure-ai-ml", "MLClient", "workspace", "model registry", "training jobs", "datasets".
development