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/sdk-newtonsoft-dependency.md

title: Explicitly reference Newtonsoft.Json package impact: MEDIUM impactDescription: Prevents build failures and security vulnerabilities from missing or outdated Newtonsoft.Json dependency tags: sdk, dotnet, dependencies, security, build-error

Explicitly reference Newtonsoft.Json package

The Azure Cosmos DB .NET SDK requires an explicit reference to Newtonsoft.Json version 13.0.3 or higher. This dependency is not managed automatically - you must add it directly to your project.

Problem (build fails without explicit reference):

// Your .csproj only references Cosmos DB SDK
<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <!-- Missing Newtonsoft.Json reference! -->
</ItemGroup>

// Build error:
// error: The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2.
// Please add a reference to Newtonsoft.Json or set the 
// 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Solution (add explicit Newtonsoft.Json reference):

<!-- Standard .csproj projects -->
<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

For projects using Central Package Management:

<!-- Directory.Packages.props -->
<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Key Points:

Always use version 13.0.3 or higher - Never use 10.x despite technical compatibility, as it has known security vulnerabilities
Required even with System.Text.Json - The dependency is needed even when using CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, because the SDK's internal operations still use Newtonsoft.Json for system types
Build check is intentional - The Cosmos DB SDK includes build targets that explicitly check for this dependency to prevent issues
Pin the version explicitly - Don't rely on transitive dependency resolution
SDK compiles against 10.x internally - But recommends 13.0.3+ to avoid security issues and conflicts

Version Compatibility:

Cosmos DB SDK Version	Minimum Secure Newtonsoft.Json	Recommended
3.47.0+	13.0.3	13.0.4
3.54.0+	13.0.4	13.0.4

Special Cases:

For library projects (not applications):

If you're building a reusable library and want to defer the Newtonsoft.Json dependency to your library's consumers, you can bypass the build check:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

⚠️ Warning: Only use this bypass for libraries. For applications, always add the explicit reference.

Troubleshooting version conflicts:

If you see package downgrade errors:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to 13.0.3

Solution:

Check which packages need which versions:

dotnet list package --include-transitive | findstr Newtonsoft.Json

Update to the highest required version in your central package management or csproj

Clean and rebuild:

dotnet clean && dotnet restore && dotnet build

Why This Matters:

Prevents build failures - The SDK will fail the build if Newtonsoft.Json is missing
Security - Version 10.x has known vulnerabilities that should be avoided
Compatibility - Ensures consistent behavior across different environments
Future-proofing - Explicit references prevent surprises when transitive dependencies change

Reference: Managing Newtonsoft.Json Dependencies

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