Cosmosdb Best Practices

ClineOfficialCreated by cosmosdb-agent-kitDistributed by Cline

Skill
Guidelines
Software development
MIT
No issues found

From the author

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

— the description by cosmosdb-agent-kit

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured set of 73+ guidelines for working with Azure Cosmos DB. It covers essential topics including data modeling, partition key design, query optimization, SDK usage, indexing, throughput scaling, global distribution, monitoring, design patterns, and vector search. The content is organized into modular rule files to assist developers in writing, reviewing, and refactoring code that interacts with the database.

What it does

Provides specific rules for designing efficient data models and choosing partition keys.
Offers guidance on optimizing queries and implementing SDK patterns.
Details strategies for indexing, throughput management, and global distribution.
Includes best practices for implementing vector search and RAG patterns.
Supplies diagnostic and monitoring recommendations for database operations.
Organizes content into categorized rule files for targeted retrieval.

When to use it

When designing data models or selecting partition keys for Cosmos DB.
When writing or refactoring application code that uses the Cosmos DB SDK.
When optimizing query performance or indexing strategies.
When configuring global distribution, throughput, or scaling settings.
When implementing vector search or advanced design patterns.

Advantages

Modular structure allows for loading only relevant rules for specific tasks.
Covers a wide range of operational and architectural concerns.
Provides clear examples of incorrect and correct implementation patterns.
Prioritizes rules by impact to guide development decisions.

Usage examples

“How should I choose a partition key for my Cosmos DB container?”: The agent will retrieve rules from the partition- prefix to explain high-cardinality, write distribution, and query alignment.
“What are the best practices for using the Cosmos DB SDK?”: The agent will load rules from the sdk- prefix to provide guidance on singleton client usage, async APIs, and retry logic.
“How do I optimize my data model for read-heavy workloads?”: The agent will reference model- prefixed rules to explain denormalization and embedding strategies.
“What should I consider when implementing vector search in Cosmos DB?”: The agent will access vector- prefixed rules to explain embedding policies, index types, and similarity search functions.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/cline/cosmosdb-best-practices/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip cosmosdb-best-practices.zip -d .agents/skills

Documentation by cosmosdb-agent-kit

Azure Cosmos DB Best Practices

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

73 individual rule files are in the rules/ directory, one file per rule, synced from the AzureCosmosDB/cosmosdb-agent-kit. Load only the relevant rule file(s) when answering a question — do NOT load all files at once.

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
Implementing vector search and RAG patterns

Rule Index

Rules are grouped by category prefix. For a given question, load files matching the relevant prefix (e.g., model-*.md for data modeling, sdk-*.md for SDK usage). See rules/_sections.md for category descriptions.

1. Data Modeling — CRITICAL (prefix: `model-`)

model-embed-related.md — Embed related data retrieved together
model-reference-large.md — Reference data when items grow large
model-avoid-2mb-limit.md — Keep items well under 2MB limit
model-id-constraints.md — Follow ID value length and character constraints
model-nesting-depth.md — Stay within 128-level nesting depth limit
model-numeric-precision.md — Understand IEEE 754 numeric precision limits
model-denormalize-reads.md — Denormalize for read-heavy workloads
model-schema-versioning.md — Version your document schemas
model-type-discriminator.md — Use type discriminators for polymorphic data
model-json-serialization.md — Handle JSON serialization correctly
model-relationship-references.md — Use ID references with transient hydration

2. Partition Key Design — CRITICAL (prefix: `partition-`)

partition-high-cardinality.md — Choose high-cardinality partition keys
partition-avoid-hotspots.md — Distribute writes evenly
partition-hierarchical.md — Use hierarchical partition keys for flexibility
partition-query-patterns.md — Align partition key with query patterns
partition-synthetic-keys.md — Create synthetic keys when needed
partition-key-length.md — Respect partition key value length limits
partition-20gb-limit.md — Plan for 20GB logical partition limit

3. Query Optimization — HIGH (prefix: `query-`)

query-avoid-cross-partition.md — Minimize cross-partition queries
query-use-projections.md — Project only needed fields
query-pagination.md — Use continuation tokens for pagination
query-avoid-scans.md — Avoid full container scans
query-parameterize.md — Use parameterized queries
query-order-filters.md — Order filters by selectivity

4. SDK Best Practices — HIGH (prefix: `sdk-`)

sdk-singleton-client.md — Reuse CosmosClient as singleton
sdk-async-api.md — Use async APIs for throughput
sdk-retry-429.md — Handle 429s with retry-after
sdk-connection-mode.md — Use Direct mode for production
sdk-preferred-regions.md — Configure preferred regions
sdk-excluded-regions.md — Exclude regions experiencing issues
sdk-availability-strategy.md — Configure availability strategy for resilience
sdk-circuit-breaker.md — Use circuit breaker for fault tolerance
sdk-diagnostics.md — Log diagnostics for troubleshooting
sdk-serialization-enums.md — Serialize enums as strings not integers
sdk-emulator-ssl.md — Configure SSL and connection mode for Cosmos DB Emulator
sdk-etag-concurrency.md — Use ETags for optimistic concurrency
sdk-java-content-response.md — Enable content response on write operations (Java)
sdk-java-cosmos-config.md — Configure Cosmos DB in Spring Boot with dependent beans
sdk-java-spring-boot-versions.md — Match Java version to Spring Boot requirements
sdk-local-dev-config.md — Configure local development to avoid cloud conflicts
sdk-newtonsoft-dependency.md — Explicitly reference Newtonsoft.Json package (.NET)
sdk-spring-data-annotations.md — Annotate entities for Spring Data Cosmos
sdk-spring-data-repository.md — Use CosmosRepository correctly

5. Indexing Strategies — MEDIUM-HIGH (prefix: `index-`)

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

6. Throughput & Scaling — MEDIUM (prefix: `throughput-`)

throughput-autoscale.md — Use autoscale for variable workloads
throughput-right-size.md — Right-size provisioned throughput
throughput-serverless.md — Consider serverless for dev/test
throughput-burst.md — Understand burst capacity
throughput-container-vs-database.md — Choose allocation level wisely

7. Global Distribution — MEDIUM (prefix: `global-`)

global-multi-region.md — Configure multi-region writes
global-consistency.md — Choose appropriate consistency level
global-conflict-resolution.md — Implement conflict resolution
global-failover.md — Configure automatic failover
global-read-regions.md — Add read regions near users
global-zone-redundancy.md — Enable zone redundancy for HA

8. Monitoring & Diagnostics — LOW-MEDIUM (prefix: `monitoring-`)

monitoring-ru-consumption.md — Track RU consumption
monitoring-latency.md — Monitor P99 latency
monitoring-throttling.md — Alert on throttling
monitoring-azure-monitor.md — Integrate Azure Monitor
monitoring-diagnostic-logs.md — Enable diagnostic logging

9. Design Patterns — HIGH (prefix: `pattern-`)

pattern-change-feed-materialized-views.md — Use Change Feed for materialized views
pattern-efficient-ranking.md — Use count-based or cached approaches for ranking
pattern-service-layer-relationships.md — Use a service layer to hydrate document references

10. Vector Search — HIGH (prefix: `vector-`)

vector-enable-feature.md — Enable vector search feature on account
vector-embedding-policy.md — Define vector embedding policy on container
vector-index-type.md — Configure vector indexes (QuantizedFlat or DiskANN)
vector-distance-query.md — Use VectorDistance() for similarity search
vector-normalize-embeddings.md — Normalize embeddings for cosine similarity
vector-repository-pattern.md — Implement repository pattern for vector search

How to Use

Each rule is a separate file under rules/. When answering a Cosmos DB question, read only the relevant rule file(s) based on the prefix matching the topic:

Data modeling question → read rules/model-*.md files
Partition key question → read rules/partition-*.md files
SDK/client question → read rules/sdk-*.md files
etc.

Each rule file contains:

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

Source: AzureCosmosDB/cosmosdb-agent-kit

Files

ATTRIBUTION.mdAdded by AutoGineer876 B
SKILL.md10.1 KiB
rules/_sections.md2.1 KiB
rules/_template.md802 B
rules/global-conflict-resolution.md4.0 KiB
rules/global-consistency.md3.7 KiB
rules/global-failover.md3.7 KiB
rules/global-multi-region.md3.2 KiB
rules/global-read-regions.md3.9 KiB
rules/global-zone-redundancy.md3.5 KiB
rules/index-composite.md6.0 KiB
rules/index-exclude-unused.md3.1 KiB
rules/index-lazy-consistent.md3.1 KiB
rules/index-range-vs-hash.md3.4 KiB
rules/index-spatial.md3.1 KiB
rules/model-avoid-2mb-limit.md2.0 KiB
rules/model-denormalize-reads.md3.4 KiB
rules/model-embed-related.md2.5 KiB
rules/model-id-constraints.md2.9 KiB
rules/model-json-serialization.md4.0 KiB
rules/model-nesting-depth.md3.3 KiB
rules/model-numeric-precision.md3.2 KiB
rules/model-reference-large.md2.3 KiB
rules/model-relationship-references.md3.6 KiB
rules/model-schema-versioning.md2.4 KiB
rules/model-type-discriminator.md3.5 KiB
rules/monitoring-azure-monitor.md4.4 KiB
rules/monitoring-diagnostic-logs.md5.1 KiB
rules/monitoring-latency.md4.2 KiB
rules/monitoring-ru-consumption.md4.2 KiB
rules/monitoring-throttling.md4.4 KiB
rules/partition-20gb-limit.md2.8 KiB
rules/partition-avoid-hotspots.md3.4 KiB
rules/partition-hierarchical.md2.7 KiB
rules/partition-high-cardinality.md2.2 KiB
rules/partition-key-length.md2.8 KiB
rules/partition-query-patterns.md2.7 KiB
rules/partition-synthetic-keys.md3.8 KiB
rules/pattern-change-feed-materialized-views.md7.2 KiB
rules/pattern-efficient-ranking.md5.8 KiB
rules/pattern-service-layer-relationships.md4.8 KiB
rules/query-avoid-cross-partition.md2.5 KiB
rules/query-avoid-scans.md2.5 KiB
rules/query-order-filters.md2.6 KiB
rules/query-pagination.md6.2 KiB
rules/query-parameterize.md2.9 KiB
rules/query-use-projections.md2.7 KiB
rules/sdk-async-api.md3.2 KiB
rules/sdk-availability-strategy.md5.3 KiB
rules/sdk-circuit-breaker.md8.4 KiB
rules/sdk-connection-mode.md2.9 KiB
rules/sdk-diagnostics.md3.6 KiB
rules/sdk-emulator-ssl.md7.8 KiB
rules/sdk-etag-concurrency.md8.1 KiB
rules/sdk-excluded-regions.md4.9 KiB
rules/sdk-java-content-response.md3.9 KiB
rules/sdk-java-cosmos-config.md5.9 KiB
rules/sdk-java-spring-boot-versions.md4.8 KiB
rules/sdk-local-dev-config.md5.4 KiB
rules/sdk-newtonsoft-dependency.md3.9 KiB
rules/sdk-preferred-regions.md3.2 KiB
rules/sdk-retry-429.md3.7 KiB
rules/sdk-serialization-enums.md2.8 KiB
rules/sdk-singleton-client.md3.7 KiB
rules/sdk-spring-data-annotations.md3.4 KiB
rules/sdk-spring-data-repository.md3.4 KiB
rules/throughput-autoscale.md2.6 KiB
rules/throughput-burst.md2.7 KiB
rules/throughput-container-vs-database.md3.2 KiB
rules/throughput-right-size.md3.1 KiB
rules/throughput-serverless.md2.7 KiB
rules/vector-distance-query.md4.8 KiB
rules/vector-embedding-policy.md3.8 KiB
rules/vector-enable-feature.md3.0 KiB
rules/vector-index-type.md4.7 KiB
rules/vector-normalize-embeddings.md8.6 KiB
rules/vector-repository-pattern.md12.9 KiB

rules/partition-key-length.md

title: Respect Partition Key Value Length Limits impact: HIGH impactDescription: prevents write failures from oversized keys tags: partition, limits, key-length, design

Respect Partition Key Value Length Limits

Azure Cosmos DB enforces a maximum partition key value length of 2,048 bytes (or 101 bytes if large partition keys are not enabled). Exceeding this limit causes write failures at runtime.

Incorrect (risk of exceeding partition key length):

// Anti-pattern: concatenating many fields into a partition key
public class Document
{
    public string Id { get; set; }
    
    // Partition key built from long descriptions - DANGER!
    public string PartitionKey => $"{TenantName}_{DepartmentName}_{TeamName}_{ProjectDescription}";
    
    public string TenantName { get; set; }       // Could be very long
    public string DepartmentName { get; set; }
    public string TeamName { get; set; }
    public string ProjectDescription { get; set; } // Unbounded user input
}

// If PartitionKey exceeds 2,048 bytes:
// Microsoft.Azure.Cosmos.CosmosException: Partition key value is too large

Correct (bounded partition key values):

// Use short, bounded identifiers for partition keys
public class Document
{
    public string Id { get; set; }
    
    // Short, deterministic IDs - always well under 2,048 bytes
    public string TenantId { get; set; }        // e.g., "t-abc123"
    public string DepartmentId { get; set; }    // e.g., "dept-42"
    
    // Partition key uses compact identifiers
    public string PartitionKey => $"{TenantId}_{DepartmentId}";
    
    // Keep long text as regular properties, not in the partition key
    public string TenantName { get; set; }
    public string DepartmentName { get; set; }
    public string ProjectDescription { get; set; }
}

// If you must derive a key from long values, hash or truncate them
public class Document
{
    public string Id { get; set; }
    public string LongCategoryPath { get; set; }  // e.g., deep taxonomy
    
    // Hash long values to a fixed-length partition key
    public string PartitionKey
    {
        get
        {
            using var sha = System.Security.Cryptography.SHA256.Create();
            var hash = sha.ComputeHash(Encoding.UTF8.GetBytes(LongCategoryPath));
            return Convert.ToBase64String(hash)[..16]; // Fixed 16-char key
        }
    }
}

Key points:

Default limit is 101 bytes without large partition key feature enabled
With large partition keys enabled, limit increases to 2,048 bytes
Enable large partition keys for new containers if you need longer values
Prefer short GUIDs, IDs, or codes over human-readable strings for partition keys

Reference: Azure Cosmos DB service quotas - Per-item limits

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

cosmosdb-agent-kit

Publisher

Cline (Official)

Distributed by

Cline

Source

cline/skills · skills/cosmosdb-best-practices · commit 2637846

Licence

MIT License (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by cosmosdb-agent-kit or Cline.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cosmosdb-best-practices.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by cosmosdb-agent-kit

Azure Cosmos DB Best Practices

When to Apply

Rule Index

1. Data Modeling — CRITICAL (prefix: model-)

2. Partition Key Design — CRITICAL (prefix: partition-)

3. Query Optimization — HIGH (prefix: query-)

4. SDK Best Practices — HIGH (prefix: sdk-)

5. Indexing Strategies — MEDIUM-HIGH (prefix: index-)

6. Throughput & Scaling — MEDIUM (prefix: throughput-)

7. Global Distribution — MEDIUM (prefix: global-)

8. Monitoring & Diagnostics — LOW-MEDIUM (prefix: monitoring-)

9. Design Patterns — HIGH (prefix: pattern-)

10. Vector Search — HIGH (prefix: vector-)