cosmosdb-best-practices
por microsoft
Guia abrangente de otimização de desempenho para aplicações Azure Cosmos DB, contendo mais de 75 regras em 11 categorias, priorizadas por impacto para orientar refatoração automatizada e geração de código.
npx skills add https://github.com/microsoft/vscode-cosmosdb --skill cosmosdb-best-practicesAzure Cosmos DB Best Practices
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.
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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Data Modeling | CRITICAL | model- |
| 2 | Partition Key Design | CRITICAL | partition- |
| 3 | Query Optimization | HIGH | query- |
| 4 | SDK Best Practices | HIGH | sdk- |
| 5 | Indexing Strategies | MEDIUM-HIGH | index- |
| 6 | Throughput & Scaling | MEDIUM | throughput- |
| 7 | Global Distribution | MEDIUM | global- |
| 8 | Monitoring & Diagnostics | LOW-MEDIUM | monitoring- |
| 9 | Design Patterns | HIGH | pattern- |
| 10 | Developer Tooling | MEDIUM | tooling- |
| 11 | Vector Search | HIGH | vector- |
Quick Reference
1. Data Modeling (CRITICAL)
- model-embed-related - Embed related data retrieved together
- model-reference-large - Reference data when items get too large
- model-avoid-2mb-limit - Keep items well under 2MB limit
- model-id-constraints - Follow ID value length and character constraints
- model-nesting-depth - Stay within 128-level nesting depth limit
- model-numeric-precision - Understand IEEE 754 numeric precision limits
- model-denormalize-reads - Denormalize for read-heavy workloads
- model-schema-versioning - Version your document schemas
- model-type-discriminator - Use type discriminators for polymorphic data
- model-json-serialization - Handle JSON serialization correctly for Cosmos DB documents
- model-relationship-references - Use ID references with transient hydration for document relationships
2. Partition Key Design (CRITICAL)
- partition-high-cardinality - Choose high-cardinality partition keys
- partition-avoid-hotspots - Distribute writes evenly
- partition-hierarchical - Use hierarchical partition keys for flexibility
- partition-query-patterns - Align partition key with query patterns
- partition-synthetic-keys - Create synthetic keys when needed
- partition-key-length - Respect partition key value length limits
- partition-20gb-limit - Plan for 20GB logical partition limit
3. Query Optimization (HIGH)
- query-avoid-cross-partition - Minimize cross-partition queries
- query-use-projections - Project only needed fields
- query-pagination - Use continuation tokens for pagination
- query-avoid-scans - Avoid full container scans
- query-parameterize - Use parameterized queries
- query-order-filters - Order filters by selectivity
- query-top-literal - Use literal integers for TOP, never parameters
4. SDK Best Practices (HIGH)
- sdk-singleton-client - Reuse CosmosClient as singleton
- sdk-async-api - Use async APIs for throughput
- sdk-retry-429 - Handle 429s with retry-after
- sdk-connection-mode - Use Direct mode for production
- sdk-preferred-regions - Configure preferred regions
- sdk-excluded-regions - Exclude regions experiencing issues
- sdk-availability-strategy - Configure availability strategy for resilience
- sdk-circuit-breaker - Use circuit breaker for fault tolerance
- sdk-diagnostics - Log diagnostics for troubleshooting
- sdk-serialization-enums - Serialize enums as strings not integers
- sdk-emulator-ssl - Configure SSL and connection mode for Cosmos DB Emulator
- sdk-etag-concurrency - Use ETags for optimistic concurrency on read-modify-write operations
- sdk-java-content-response - Enable content response on write operations (Java)
- sdk-java-cosmos-config - Configure Cosmos DB initialization correctly in Spring Boot
- sdk-java-spring-boot-versions - Match Java version to Spring Boot requirements
- sdk-local-dev-config - Configure local development to avoid cloud conflicts
- sdk-newtonsoft-dependency - Explicitly reference Newtonsoft.Json package
- sdk-python-async-deps - Include aiohttp when using Python async SDK
- sdk-spring-data-annotations - Annotate entities for Spring Data Cosmos
- sdk-spring-data-repository - Use CosmosRepository correctly and handle Iterable return types
5. Indexing Strategies (MEDIUM-HIGH)
- index-path-syntax - Use correct indexing path syntax (
/?for scalars,/[]for arrays,/*terminal-only) - index-exclude-unused - Exclude paths never queried
- index-composite - Use composite indexes for ORDER BY
- index-composite-direction - Match composite index directions to ORDER BY
- index-spatial - Add spatial indexes for geo queries
- index-range-vs-hash - Choose appropriate index types
- index-lazy-consistent - Understand indexing modes
6. Throughput & Scaling (MEDIUM)
- throughput-autoscale - Use autoscale for variable workloads
- throughput-right-size - Right-size provisioned throughput
- throughput-serverless - Consider serverless for dev/test
- throughput-burst - Understand burst capacity
- throughput-container-vs-database - Choose allocation level wisely
7. Global Distribution (MEDIUM)
- global-multi-region - Configure multi-region writes
- global-consistency - Choose appropriate consistency level
- global-conflict-resolution - Implement conflict resolution
- global-failover - Configure automatic failover
- global-read-regions - Add read regions near users
- global-zone-redundancy - Enable zone redundancy for HA
8. Monitoring & Diagnostics (LOW-MEDIUM)
- monitoring-ru-consumption - Track RU consumption
- monitoring-latency - Monitor P99 latency
- monitoring-throttling - Alert on throttling
- monitoring-azure-monitor - Integrate Azure Monitor
- monitoring-diagnostic-logs - Enable diagnostic logging
9. Design Patterns (HIGH)
- pattern-change-feed-materialized-views - Use Change Feed for cross-partition query optimization
- pattern-efficient-ranking - Use count-based or cached approaches for efficient ranking
- pattern-service-layer-relationships - Use a service layer to hydrate document references
10. Developer Tooling (MEDIUM)
- tooling-vscode-extension - Use the VS Code extension for routine inspection and management
- tooling-emulator-setup - Use the Emulator for local development and testing
11. Vector Search (HIGH)
- vector-enable-feature - Enable vector search on the account before using vector features
- vector-embedding-policy - Define vector embedding policy for vector properties
- vector-index-type - Configure vector indexes in the indexing policy
- vector-normalize-embeddings - Normalize embeddings for cosine similarity
- vector-distance-query - Use VectorDistance for similarity search
- vector-repository-pattern - Implement a repository pattern for vector search
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
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
Mais skills de microsoft
oss-growth
microsoft
Persona de growth hacker OSS
official
microsoft-foundry
microsoft
Implantar, avaliar e gerenciar agentes Foundry de ponta a ponta: build Docker, push ACR, criação de agente hospedado/prompt, inicialização de contêiner, avaliação em lote, avaliação contínua, fluxos de trabalho do otimizador de prompt, agent.yaml, curadoria de conjunto de dados a partir de rastros. USE PARA: implantar agente no Foundry, agente hospedado, criar agente, invocar agente, avaliar agente, executar avaliação em lote, avaliação contínua, monitoramento contínuo, status da avaliação contínua, otimizar prompt, melhorar prompt, otimizador de prompt, otimizar instruções do agente, melhorar agente...
officialdevelopmentdevops
azure-ai
microsoft
Use para Azure AI: Search, Speech, OpenAI, Document Intelligence. Ajuda com pesquisa, busca vetorial/híbrida, fala para texto, texto para fala, transcrição, OCR. QUANDO: AI Search, pesquisa de consulta, busca vetorial, busca híbrida, busca semântica, fala para texto, texto para fala, transcrever, OCR, converter texto em fala.
officialdevelopmentapi
azure-deploy
microsoft
Execute implantações do Azure para aplicativos JÁ PREPARADOS que possuem arquivos .azure/deployment-plan.md e de infraestrutura existentes. NÃO use esta skill quando o usuário pedir para CRIAR um novo aplicativo — use azure-prepare. Esta skill executa comandos azd up, azd deploy, terraform apply e az deployment com recuperação de erros integrada. Requer .azure/deployment-plan.md do azure-prepare e status validado do azure-validate. QUANDO: "executar azd up", "executar azd deploy", "executar implantação",...
officialdevopsaws
azure-storage
microsoft
Serviços de Armazenamento do Azure, incluindo Blob Storage, File Shares, Queue Storage, Table Storage e Data Lake. Responde a perguntas sobre camadas de acesso ao armazenamento (hot, cool, cold, archive), quando usar cada camada e comparação entre elas. Oferece armazenamento de objetos, compartilhamentos de arquivos SMB, mensagens assíncronas, NoSQL chave-valor e análise de big data. Inclui gerenciamento de ciclo de vida. USE PARA: blob storage, file shares, queue storage, table storage, data lake, upload de arquivos, download de blobs, contas de armazenamento, camadas de acesso,...
officialdevelopmentdatabase
azure-diagnostics
microsoft
Depure problemas de produção no Azure usando AppLens, Azure Monitor, integridade de recursos e triagem segura. QUANDO: depurar problemas de produção, solucionar problemas do Serviço de Aplicativo, alto uso de CPU no Serviço de Aplicativo, falha de implantação do Serviço de Aplicativo, solucionar problemas de aplicativos em contêineres, solucionar problemas de funções, solucionar problemas do AKS, kubectl não consegue conectar, falhas do kube-system/CoreDNS, pod pendente, crashloop, nó não pronto, falhas de atualização, analisar logs, KQL, insights, falhas ao puxar imagem, problemas de inicialização a frio, falhas de sonda de integridade,...
officialdevopsdevelopment
azure-prepare
microsoft
Prepare aplicativos do Azure para implantação (infra Bicep/Terraform, azure.yaml, Dockerfiles). Use para criar/modernizar ou criar+implantar; não para migração entre nuvens (use azure-cloud-migrate). NÃO USE PARA: aplicativos copilot-sdk (use azure-hosted-copilot-sdk). QUANDO: "criar aplicativo", "construir aplicativo web", "criar API", "criar API HTTP serverless", "criar frontend", "criar backend", "construir um serviço", "modernizar aplicativo", "atualizar aplicativo", "adicionar autenticação", "adicionar cache", "hospedar no Azure", "criar e...
officialdevelopmentdevops
azure-validate
microsoft
Validação pré-implantação para prontidão do Azure. Execute verificações aprofundadas de configuração, infraestrutura (Bicep ou Terraform), atribuições de função RBAC, permissões de identidade gerenciada e pré-requisitos antes de implantar. QUANDO: validar meu aplicativo, verificar prontidão para implantação, executar verificações de pré-voo, verificar configuração, verificar se está pronto para implantar, validar azure.yaml, validar Bicep, testar antes de implantar, solucionar erros de implantação, validar Azure Functions, validar function app, validar serverless...
officialdevopstesting