cosmosdb-best-practices
por microsoft
Guía completa de optimización de rendimiento para aplicaciones de Azure Cosmos DB, que contiene más de 75 reglas en 11 categorías, priorizadas por impacto para guiar la refactorización automatizada y la generación 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
Más skills de microsoft
oss-growth
microsoft
Persona de growth hacker de OSS
official
microsoft-foundry
microsoft
Implementar, evaluar y gestionar agentes de Foundry de extremo a extremo: compilación de Docker, envío a ACR, creación de agente alojado/de prompt, inicio de contenedor, evaluación por lotes, evaluación continua, flujos de trabajo del optimizador de prompts, agent.yaml, curación de conjuntos de datos a partir de trazas. USAR PARA: implementar agente en Foundry, agente alojado, crear agente, invocar agente, evaluar agente, ejecutar evaluación por lotes, evaluación continua, monitoreo continuo, estado de evaluación continua, optimizar prompt, mejorar prompt, optimizador de prompts, optimizar instrucciones del agente, mejorar agente...
officialdevelopmentdevops
azure-ai
microsoft
Útil para Azure AI: Search, Speech, OpenAI, Document Intelligence. Ayuda con búsqueda, búsqueda vectorial/híbrida, voz a texto, texto a voz, transcripción, OCR. CUANDO: AI Search, búsqueda de consultas, búsqueda vectorial, búsqueda híbrida, búsqueda semántica, voz a texto, texto a voz, transcribir, OCR, convertir texto a voz.
officialdevelopmentapi
azure-deploy
microsoft
Ejecuta despliegues en Azure para aplicaciones YA PREPARADAS que tengan archivos .azure/deployment-plan.md e infraestructura existentes. NO uses esta habilidad cuando el usuario solicite CREAR una nueva aplicación — usa azure-prepare en su lugar. Esta habilidad ejecuta comandos azd up, azd deploy, terraform apply y az deployment con recuperación de errores integrada. Requiere .azure/deployment-plan.md de azure-prepare y estado validado de azure-validate. CUANDO: "ejecutar azd up", "ejecutar azd deploy", "ejecutar despliegue",...
officialdevopsaws
azure-storage
microsoft
Servicios de Azure Storage que incluyen Blob Storage, File Shares, Queue Storage, Table Storage y Data Lake. Responde preguntas sobre niveles de acceso de almacenamiento (hot, cool, cold, archive), cuándo usar cada nivel y comparación entre niveles. Proporciona almacenamiento de objetos, recursos compartidos de archivos SMB, mensajería asíncrona, NoSQL clave-valor y análisis de big data. Incluye gestión del ciclo de vida. USAR PARA: blob storage, file shares, queue storage, table storage, data lake, subir archivos, descargar blobs, cuentas de almacenamiento, niveles de acceso,...
officialdevelopmentdatabase
azure-diagnostics
microsoft
Depura problemas de producción en Azure usando AppLens, Azure Monitor, estado de recursos y triaje seguro. CUANDO: depurar problemas de producción, solucionar problemas de App Service, CPU alta en App Service, fallo de implementación de App Service, solucionar problemas de Container Apps, solucionar problemas de Functions, solucionar problemas de AKS, kubectl no puede conectar, fallos de kube-system/CoreDNS, pod pendiente, crashloop, nodo no listo, fallos de actualización, analizar registros, KQL, información, fallos de extracción de imágenes, problemas de arranque en frío, fallos de sondeo de estado,...
officialdevopsdevelopment
azure-prepare
microsoft
Prepara aplicaciones de Azure para el despliegue (infra Bicep/Terraform, azure.yaml, Dockerfiles). Úselo para crear/modernizar o crear+desplegar; no para migración entre nubes (use azure-cloud-migrate). NO USAR PARA: aplicaciones copilot-sdk (use azure-hosted-copilot-sdk). CUANDO: "crear aplicación", "construir aplicación web", "crear API", "crear API HTTP sin servidor", "crear frontend", "crear backend", "construir un servicio", "modernizar aplicación", "actualizar aplicación", "agregar autenticación", "agregar almacenamiento en caché", "alojar en Azure", "crear y...
officialdevelopmentdevops
azure-validate
microsoft
Validación previa al despliegue para la preparación en Azure. Realiza verificaciones exhaustivas de configuración, infraestructura (Bicep o Terraform), asignaciones de roles RBAC, permisos de identidad administrada y requisitos previos antes de desplegar. CUÁNDO: validar mi aplicación, verificar preparación para el despliegue, ejecutar comprobaciones previas, verificar configuración, comprobar si está listo para desplegar, validar azure.yaml, validar Bicep, probar antes de desplegar, solucionar errores de despliegue, validar Azure Functions, validar aplicación de funciones, validar serverless...
officialdevopstesting