cosmosdb-best-practices

Azure Cosmos DB应用程序的全面性能优化指南，包含11个类别的75+条规则，按影响优先级排序，用于指导自动重构和代码生成。

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

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