cosmosdb-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Cosmos DB Best Practices

Azure Cosmos DB 最佳实践

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

这是一份针对Azure Cosmos DB应用的全面性能优化指南，包含8个类别下的45+条规则，按影响优先级排序，可指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Designing data models for Cosmos DB
Choosing partition keys
Writing or optimizing queries
Implementing SDK patterns
Reviewing code for performance issues
Configuring throughput and scaling
Building globally distributed applications

在以下场景中可参考本指南：

为Cosmos DB设计数据模型时
选择分区键时
编写或优化查询时
实现SDK模式时
审查代码以排查性能问题时
配置吞吐量和扩缩容时
构建全球分布式应用时

Rule Categories by Priority

按优先级划分的规则类别


model-
partition-
query-
sdk-
index-
throughput-
global-
monitoring-

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


model-
partition-
query-
sdk-
index-
throughput-
global-
monitoring-

优先级	类别	影响程度	前缀
1	数据建模	关键	`model-`
2	分区键设计	关键	`partition-`
3	查询优化	高	`query-`
4	SDK最佳实践	高	`sdk-`
5	索引策略	中高	`index-`
6	吞吐量与扩缩容	中	`throughput-`
7	全球分布式部署	中	`global-`
8	监控与诊断	中低	`monitoring-`

Quick Reference

快速参考

1. Data Modeling (CRITICAL)

1. 数据建模（关键）

```
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-denormalize-reads
```
- Denormalize for read-heavy workloads
```
model-schema-versioning
```
- Version your document schemas
```
model-type-discriminator
```
- Use type discriminators for polymorphic data

```
model-embed-related
```
- 嵌入需一起检索的关联数据
```
model-reference-large
```
- 当数据项过大时使用引用方式
```
model-avoid-2mb-limit
```
- 确保数据项远小于2MB限制
```
model-denormalize-reads
```
- 针对读密集型工作负载采用反范式设计
```
model-schema-versioning
```
- 为文档模式添加版本控制
```
model-type-discriminator
```
- 对多态数据使用类型鉴别器

2. Partition Key Design (CRITICAL)

2. 分区键设计（关键）

```
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-20gb-limit
```
- Plan for 20GB logical partition limit

```
partition-high-cardinality
```
- 选择高基数分区键
```
partition-avoid-hotspots
```
- 均匀分配写入操作
```
partition-hierarchical
```
- 使用分层分区键提升灵活性
```
partition-query-patterns
```
- 使分区键与查询模式对齐
```
partition-synthetic-keys
```
- 必要时创建合成键
```
partition-20gb-limit
```
- 为20GB逻辑分区限制提前规划

3. Query Optimization (HIGH)

3. 查询优化（高）

```
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-avoid-cross-partition
```
- 尽量减少跨分区查询
```
query-use-projections
```
- 仅投影所需字段
```
query-pagination
```
- 使用延续令牌实现分页
```
query-avoid-scans
```
- 避免全容器扫描
```
query-parameterize
```
- 使用参数化查询
```
query-order-filters
```
- 按选择性对筛选器排序

4. SDK Best Practices (HIGH)

4. SDK最佳实践（高）

```
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-java-content-response
```
- Enable content response on write operations (Java)
```
sdk-java-spring-boot-versions
```
- Match Java version to Spring Boot requirements
```
sdk-local-dev-config
```
- Configure local development to avoid cloud conflicts

```
sdk-singleton-client
```
- 将CosmosClient作为单例复用
```
sdk-async-api
```
- 使用异步API提升吞吐量
```
sdk-retry-429
```
- 结合retry-after处理429错误
```
sdk-connection-mode
```
- 生产环境使用Direct模式
```
sdk-preferred-regions
```
- 配置首选区域
```
sdk-excluded-regions
```
- 排除出现问题的区域
```
sdk-availability-strategy
```
- 配置可用性策略以提升韧性
```
sdk-circuit-breaker
```
- 使用断路器实现容错
```
sdk-diagnostics
```
- 记录诊断信息用于故障排查
```
sdk-serialization-enums
```
- 将枚举序列化为字符串而非整数
```
sdk-emulator-ssl
```
- 为Cosmos DB模拟器配置SSL和连接模式
```
sdk-java-content-response
```
- 在写入操作上启用内容响应（Java）
```
sdk-java-spring-boot-versions
```
- 使Java版本与Spring Boot要求匹配
```
sdk-local-dev-config
```
- 配置本地开发环境以避免云服务冲突

5. Indexing Strategies (MEDIUM-HIGH)

5. 索引策略（中高）

```
index-exclude-unused
```
- Exclude paths never queried
```
index-composite
```
- Use composite indexes for ORDER BY
```
index-spatial
```
- Add spatial indexes for geo queries
```
index-range-vs-hash
```
- Choose appropriate index types
```
index-lazy-consistent
```
- Understand indexing modes

```
index-exclude-unused
```
- 排除从未被查询的路径
```
index-composite
```
- 为ORDER BY操作使用复合索引
```
index-spatial
```
- 为地理查询添加空间索引
```
index-range-vs-hash
```
- 选择合适的索引类型
```
index-lazy-consistent
```
- 了解索引模式

6. Throughput & Scaling (MEDIUM)

6. 吞吐量与扩缩容（中）

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

```
throughput-autoscale
```
- 针对可变工作负载使用自动扩缩容
```
throughput-right-size
```
- 合理配置预配吞吐量
```
throughput-serverless
```
- 开发/测试环境可考虑无服务器模式
```
throughput-burst
```
- 了解突发容量机制
```
throughput-container-vs-database
```
- 谨慎选择吞吐量分配级别

7. Global Distribution (MEDIUM)

7. 全球分布式部署（中）

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

```
global-multi-region
```
- 配置多区域写入
```
global-consistency
```
- 选择合适的一致性级别
```
global-conflict-resolution
```
- 实现冲突解决机制
```
global-failover
```
- 配置自动故障转移
```
global-read-regions
```
- 在用户附近添加读取区域
```
global-zone-redundancy
```
- 启用区域冗余以实现高可用

8. Monitoring & Diagnostics (LOW-MEDIUM)

8. 监控与诊断（中低）

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

```
monitoring-ru-consumption
```
- 跟踪RU消耗
```
monitoring-latency
```
- 监控P99延迟
```
monitoring-throttling
```
- 针对限流设置告警
```
monitoring-azure-monitor
```
- 集成Azure Monitor
```
monitoring-diagnostic-logs
```
- 启用诊断日志

9. Design Patterns (HIGH)

9. 设计模式（高）

```
pattern-change-feed-materialized-views
```
- Use Change Feed for cross-partition query optimization

```
pattern-change-feed-materialized-views
```
- 使用Change Feed优化跨分区查询

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/model-embed-related.md
rules/partition-high-cardinality.md
rules/_sections.md

Each rule file contains:

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

阅读单个规则文件获取详细说明和代码示例：

rules/model-embed-related.md
rules/partition-high-cardinality.md
rules/_sections.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外背景信息和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南：

AGENTS.md