Cosmosdb Best Practices

microsoft/cosmosdb-best-practices

| Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage. Use when writing, reviewing, or refactoring code that interacts with Azure Cosmos DB, designing data models, optimizing queries, or implementing high-performance database operations.

85k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

198

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

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

What comes with it

153 941 bytes besides the instruction

rules/global-conflict-resolution.md

rules/global-consistency.md

rules/global-failover.md

rules/global-multi-region.md

rules/global-read-regions.md

rules/global-zone-redundancy.md

rules/index-composite-direction.md

rules/index-composite.md

rules/index-exclude-unused.md

rules/index-lazy-consistent.md

rules/index-path-syntax.md

rules/index-range-vs-hash.md

rules/index-spatial.md

rules/model-avoid-2mb-limit.md

rules/model-denormalize-reads.md

rules/model-embed-related.md

rules/model-id-constraints.md

rules/model-json-serialization.md

rules/model-nesting-depth.md

rules/model-numeric-precision.md

rules/model-reference-large.md

rules/model-relationship-references.md

rules/model-schema-versioning.md

rules/model-type-discriminator.md

rules/monitoring-azure-monitor.md

rules/monitoring-diagnostic-logs.md

rules/monitoring-latency.md

rules/monitoring-ru-consumption.md

rules/monitoring-throttling.md

rules/partition-20gb-limit.md

rules/partition-avoid-hotspots.md

rules/partition-hierarchical.md

rules/partition-high-cardinality.md

rules/partition-key-length.md

rules/partition-query-patterns.md

rules/partition-synthetic-keys.md

rules/pattern-change-feed-materialized-views.md

rules/pattern-efficient-ranking.md

rules/pattern-service-layer-relationships.md

rules/query-avoid-cross-partition.md

The instruction itself

17 sections, as written by the author

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

|----------|----------|--------|--------|

| 4 | SDK Best Practices | HIGH | sdk- |

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

How to use it

Copy the folder

Take microsoft/cosmosdb-best-practices from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.