cosmosdb-best-practices
installsforks
How to install cosmosdb-best-practices?
azurecosmosdb/cosmosdb-agent-kit/cosmosdb-best-practices
$npx -y skills add AzureCosmosDB/cosmosdb-agent-kit --skill cosmosdb-best-practicesAzure 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-performanc
SKILL.md
| 1 | # Azure Cosmos DB Best Practices |
| 2 | |
| 3 | Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 100+ rules across 12 categories, prioritized by impact to guide automated refactoring and code generation. |
| 4 | |
| 5 | ## When to Apply |
| 6 | |
| 7 | Reference these guidelines when: |
| 8 | - Designing data models for Cosmos DB |
| 9 | - Choosing partition keys |
| 10 | - Writing or optimizing queries |
| 11 | - Implementing SDK patterns |
| 12 | - Using the Cosmos DB Emulator for local development |
| 13 | - Inspecting or managing Cosmos DB data with developer tooling |
| 14 | - Implementing vector search or RAG features on Cosmos DB |
| 15 | - Reviewing code for performance issues |
| 16 | - Configuring throughput and scaling |
| 17 | - Building globally distributed applications |
| 18 | |
| 19 | ## Rule Categories by Priority |
| 20 | |
| 21 | | Priority | Category | Impact | Prefix | |
| 22 | |----------|----------|--------|--------| |
| 23 | | 1 | Data Modeling | CRITICAL | `model-` | |
| 24 | | 2 | Partition Key Design | CRITICAL | `partition-` | |
| 25 | | 3 | Query Optimization | HIGH | `query-` | |
| 26 | | 4 | SDK Best Practices | HIGH | `sdk-` | |
| 27 | | 5 | Indexing Strategies | MEDIUM-HIGH | `index-` | |
| 28 | | 6 | Throughput & Scaling | MEDIUM | `throughput-` | |
| 29 | | 7 | Global Distribution | MEDIUM | `global-` | |
| 30 | | 8 | Monitoring & Diagnostics | LOW-MEDIUM | `monitoring-` | |
| 31 | | 9 | Design Patterns | HIGH | `pattern-` | |
| 32 | | 10 | Developer Tooling | MEDIUM | `tooling-` | |
| 33 | | 11 | Vector Search | HIGH | `vector-` | |
| 34 | |
| 35 | ## Quick Reference |
| 36 | |
| 37 | ### 1. Data Modeling (CRITICAL) |
| 38 | |
| 39 | - [model-embed-related](rules/model-embed-related.md) - Embed related data retrieved together |
| 40 | - [model-reference-large](rules/model-reference-large.md) - Reference data when items get too large |
| 41 | - [model-avoid-2mb-limit](rules/model-avoid-2mb-limit.md) - Keep items well under 2MB limit |
| 42 | - [model-id-constraints](rules/model-id-constraints.md) - Follow ID value length and character constraints |
| 43 | - [model-nesting-depth](rules/model-nesting-depth.md) - Stay within 128-level nesting depth limit |
| 44 | - [model-numeric-precision](rules/model-numeric-precision.md) - Understand IEEE 754 numeric precision limits |
| 45 | - [model-denormalize-reads](rules/model-denormalize-reads.md) - Denormalize for read-heavy workloads including pre-computed aggregates |
| 46 | - [model-schema-versioning](rules/model-schema-versioning.md) - Version your document schemas |
| 47 | - [model-type-discriminator](rules/model-type-discriminator.md) - Use type discriminators for polymorphic data |
| 48 | - [model-json-serialization](rules/model-json-serialization.md) - Handle JSON serialization correctly for Cosmos DB documents |
| 49 | - [model-relationship-references](rules/model-relationship-references.md) - Use ID references with transient hydration for document relationships |
| 50 | |
| 51 | ### 2. Partition Key Design (CRITICAL) |
| 52 | |
| 53 | - [partition-high-cardinality](rules/partition-high-cardinality.md) - Choose high-cardinality partition keys |
| 54 | - [partition-avoid-hotspots](rules/partition-avoid-hotspots.md) - Distribute writes evenly |
| 55 | - [partition-hierarchical](rules/partition-hierarchical.md) - Use hierarchical partition keys for flexibility; order levels broad→narrow |
| 56 | - [partition-query-patterns](rules/partition-query-patterns.md) - Align partition key with query patterns |
| 57 | - [partition-synthetic-keys](rules/partition-synthetic-keys.md) - Create synthetic keys when needed |
| 58 | - [partition-key-length](rules/partition-key-length.md) - Respect partition key value length limits |
| 59 | - [partition-immutable-key](rules/partition-immutable-key.md) - Choose immutable properties as partition keys |
| 60 | - [partition-20gb-limit](rules/partition-20gb-limit.md) - Plan for 20GB logical partition limit |
| 61 | - [partition-rekey-migration](rules/partition-rekey-migration.md) - Re-key a misaligned container with the Change partition key feature |
| 62 | |
| 63 | ### 3. Query Optimization (HIGH) |
| 64 | |
| 65 | - [query-aggregate-single-pass](rules/query-aggregate-single-pass.md) - Compute min/max/avg with one scoped aggregate query |
| 66 | - [query-avoid-cross-partition](rules/query-avoid-cross-partition.md) - Minimize cross-partition queries |
| 67 | - [query-use-projections](rules/query-use-projections.md) - Project only needed fields; prefer dedicated result typ |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
