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://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-synthetic-keys.md

title: Create Synthetic Partition Keys When Needed impact: HIGH impactDescription: optimizes for multiple access patterns tags: partition, synthetic-key, composite, design

Create Synthetic Partition Keys When Needed

When no single natural field serves as an ideal partition key, create a synthetic key by combining multiple fields.

Incorrect (forced to choose suboptimal natural key):

// IoT scenario: need to query by device AND time range
public class Telemetry
{
    public string Id { get; set; }
    public string DeviceId { get; set; }  // Partition key?
    public DateTime Timestamp { get; set; }
    public double Value { get; set; }
}

// If partitioned by DeviceId alone:
// - Old data accumulates forever in same partition
// - Time-range queries still scan entire partition

// If partitioned by Timestamp alone:
// - Device queries are cross-partition
// - Hot partition on current time

Correct (synthetic partition key):

public class Telemetry
{
    public string Id { get; set; }
    public string DeviceId { get; set; }
    public DateTime Timestamp { get; set; }
    public double Value { get; set; }
    
    // Synthetic key combining device + time bucket
    public string PartitionKey => $"{DeviceId}_{Timestamp:yyyy-MM}";
}

// Creates partitions like: "device123_2026-01", "device123_2026-02"
// Benefits:
// - Single device's data spreads across time-based partitions
// - Time-range queries can target specific partitions
// - No partition grows indefinitely

// Query device for specific month - single partition
var query = container.GetItemQueryIterator<Telemetry>(
    new QueryDefinition("SELECT * FROM c WHERE c.deviceId = @device")
        .WithParameter("@device", deviceId),
    requestOptions: new QueryRequestOptions
    {
        PartitionKey = new PartitionKey($"{deviceId}_2026-01")
    });

// Multi-tenant with user-level isolation
public class UserDocument
{
    public string Id { get; set; }
    public string TenantId { get; set; }
    public string UserId { get; set; }
    
    // Synthetic key for tenant + user isolation
    public string PartitionKey => $"{TenantId}:{UserId}";
}

// Each user gets their own partition within tenant
// Query all user's docs - single partition
// Query tenant's docs - targeted cross-partition (just that tenant's users)

// Order system with synthetic key
public class Order
{
    public string Id { get; set; }
    public string CustomerId { get; set; }
    public DateTime OrderDate { get; set; }
    
    // Combine customer + year for bounded partition growth
    public string PartitionKey => $"{CustomerId}_{OrderDate:yyyy}";
}

Evaluate Hierarchical Partition Keys (HPK) when considering Synthetic Partition keys:

When suggesting synthetic partition keys as part of design, evaluate Hierarchical Partition Keys (HPK) as an alternative that provides efficient multi-level query boundaries without synthetic key complexity. (HPK natively supports efficient prefix-based cross-partition queries that synthetic keys cannot.)

** Synthetic Key vs Hierarchical PK - Comparison table:**

Feature	Synthetic Key	Hierarchical PK
Query boundaries	Manual `STARTSWITH()`	Native prefix queries
Key construction	Application-level string concat	Cosmos DB native
Prefix queries	Inefficient (cross-partition)	Efficient (targeted)

References:

Additional HPK Considerations: Evaluate HPK limitations and known issues for some SDKs, various connectors and account for Hierarchical Cardinality requirements of all levels.

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

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