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/index-composite.md

title: Use Composite Indexes for ORDER BY impact: HIGH impactDescription: enables sorted queries, reduces RU tags: index, composite, orderby, sorting

Use Composite Indexes for ORDER BY

Create composite indexes for queries with ORDER BY on multiple properties. Without them, queries may fail or require expensive client-side sorting.

Incorrect (ORDER BY without composite index):

// Query with multi-property ORDER BY
var query = @"
    SELECT * FROM c 
    WHERE c.status = 'active' 
    ORDER BY c.createdAt DESC, c.priority ASC";

// Without composite index, this may:
// 1. Fail with: "Order-by item requires a corresponding composite index"
// 2. Or consume excessive RU for sorting

Correct (composite index for ORDER BY):

// Create composite index matching the ORDER BY
var indexingPolicy = new IndexingPolicy
{
    IndexingMode = IndexingMode.Consistent,
    
    CompositeIndexes =
    {
        // Must match ORDER BY exactly (properties and sort order)
        new Collection<CompositePath>
        {
            new CompositePath { Path = "/createdAt", Order = CompositePathSortOrder.Descending },
            new CompositePath { Path = "/priority", Order = CompositePathSortOrder.Ascending }
        },
        
        // Add reverse order for flexibility
        new Collection<CompositePath>
        {
            new CompositePath { Path = "/createdAt", Order = CompositePathSortOrder.Ascending },
            new CompositePath { Path = "/priority", Order = CompositePathSortOrder.Descending }
        },
        
        // Common filter + sort pattern
        new Collection<CompositePath>
        {
            new CompositePath { Path = "/status", Order = CompositePathSortOrder.Ascending },
            new CompositePath { Path = "/createdAt", Order = CompositePathSortOrder.Descending }
        }
    }
};

var containerProperties = new ContainerProperties
{
    Id = "tasks",
    PartitionKeyPath = "/userId",
    IndexingPolicy = indexingPolicy
};

// JSON indexing policy with composite indexes
{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        { "path": "/*" }
    ],
    "compositeIndexes": [
        [
            { "path": "/status", "order": "ascending" },
            { "path": "/createdAt", "order": "descending" }
        ],
        [
            { "path": "/createdAt", "order": "descending" },
            { "path": "/priority", "order": "ascending" }
        ]
    ]
}

// Common patterns that need composite indexes:

// Pattern 1: Filter + Sort
// WHERE status = 'x' ORDER BY date DESC
new Collection<CompositePath>
{
    new CompositePath { Path = "/status", Order = CompositePathSortOrder.Ascending },
    new CompositePath { Path = "/date", Order = CompositePathSortOrder.Descending }
}

// Pattern 2: Multi-column sort
// ORDER BY lastName ASC, firstName ASC
new Collection<CompositePath>
{
    new CompositePath { Path = "/lastName", Order = CompositePathSortOrder.Ascending },
    new CompositePath { Path = "/firstName", Order = CompositePathSortOrder.Ascending }
}

// Pattern 3: Range + Sort
// WHERE price >= 10 ORDER BY rating DESC
new Collection<CompositePath>
{
    new CompositePath { Path = "/price", Order = CompositePathSortOrder.Ascending },
    new CompositePath { Path = "/rating", Order = CompositePathSortOrder.Descending }
}

Multi-Tenant Composite Index Patterns

In multi-tenant designs using type discriminators and hierarchical partition keys, composite indexes are critical for queries that filter by entity type and sort by common fields:

// Multi-tenant SaaS: tasks by status, sorted by date
{
    "compositeIndexes": [
        [
            { "path": "/type", "order": "ascending" },
            { "path": "/status", "order": "ascending" },
            { "path": "/createdAt", "order": "descending" }
        ],
        [
            { "path": "/type", "order": "ascending" },
            { "path": "/assigneeId", "order": "ascending" },
            { "path": "/dueDate", "order": "ascending" }
        ],
        [
            { "path": "/type", "order": "ascending" },
            { "path": "/priority", "order": "descending" },
            { "path": "/createdAt", "order": "descending" }
        ]
    ]
}

// Java: Composite indexes with IndexingPolicy
IndexingPolicy policy = new IndexingPolicy();

// Type + Status + Date (for: WHERE type='task' AND status='open' ORDER BY createdAt DESC)
List<CompositePath> statusSort = Arrays.asList(
    new CompositePath().setPath("/type").setOrder(CompositePathSortOrder.ASCENDING),
    new CompositePath().setPath("/status").setOrder(CompositePathSortOrder.ASCENDING),
    new CompositePath().setPath("/createdAt").setOrder(CompositePathSortOrder.DESCENDING)
);

// Type + Assignee + DueDate (for: WHERE type='task' AND assigneeId=@id ORDER BY dueDate)
List<CompositePath> assigneeSort = Arrays.asList(
    new CompositePath().setPath("/type").setOrder(CompositePathSortOrder.ASCENDING),
    new CompositePath().setPath("/assigneeId").setOrder(CompositePathSortOrder.ASCENDING),
    new CompositePath().setPath("/dueDate").setOrder(CompositePathSortOrder.ASCENDING)
);

policy.setCompositeIndexes(Arrays.asList(statusSort, assigneeSort));

Why type discriminators need composite indexes: When a single container holds multiple entity types (tenant, user, project, task), queries always filter by type. Without a composite index on (type, sortField), the query engine cannot efficiently sort within a single entity type. This is especially costly in containers with millions of mixed-type documents.

Rules:

Composite index order must match ORDER BY exactly
First path can be equality filter
Include both ASC/DESC variants for flexibility
Maximum 8 paths per composite index
Always define composite indexes when using type discriminators in shared containers
Include /type as the first path in multi-tenant composite indexes

Reference: Composite indexes

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