AutoGineer
Generated banner for Cosmosdb Best Practices
Generated logo for Cosmosdb Best Practices

Cosmosdb Best Practices

ClineOfficialCreated by cosmosdb-agent-kitDistributed by Cline

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/cline/cosmosdb-best-practices/download

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

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

rules/pattern-change-feed-materialized-views.md

title: Use Change Feed for cross-partition query optimization with materialized views impact: HIGH impactDescription: eliminates cross-partition query overhead for admin/analytics scenarios tags: pattern, change-feed, materialized-views, cross-partition, query-optimization

Use Change Feed for Materialized Views or Global Secondary Index

When your application requires frequent cross-partition queries (e.g., admin dashboards, analytics, frequent lookups by secondary non-PK attributes), you have two main options: use Change Feed to maintain materialized views in a separate container optimized for those query patterns, or use the new Global Secondary Index (GSI).

Problem: Cross-partition queries are expensive

// This query fans out to ALL partitions - expensive at scale!
// Container partitioned by /customerId
var query = container.GetItemQueryIterator<Order>(
    "SELECT * FROM c WHERE c.status = 'Pending' ORDER BY c.createdAt DESC"
);
// With 100,000 customers = 100,000+ physical partitions queried

Cross-partition queries:

  • Consume RUs from every partition (high cost)

  • Have higher latency (parallel fan-out)

  • Don't scale well as data grows

Solution: Materialized view with Change Feed

Create a second container optimized for your admin queries:

Container 1: "orders" (partitioned by /customerId)
├── Efficient for: customer order history, point reads
└── Pattern: Single-partition queries

Container 2: "orders-by-status" (partitioned by /status)  
├── Efficient for: admin status queries
├── Pattern: Single-partition queries within status
└── Populated by: Change Feed processor

Implementation - .NET:

// Change Feed processor to sync materialized view
Container leaseContainer = database.GetContainer("leases");
Container ordersContainer = database.GetContainer("orders");
Container ordersByStatusContainer = database.GetContainer("orders-by-status");

ChangeFeedProcessor processor = ordersContainer
    .GetChangeFeedProcessorBuilder<Order>("statusViewProcessor", HandleChangesAsync)
    .WithInstanceName("instance-1")
    .WithLeaseContainer(leaseContainer)
    .WithStartFromBeginning()
    .Build();

async Task HandleChangesAsync(
    IReadOnlyCollection<Order> changes, 
    CancellationToken cancellationToken)
{
    foreach (Order order in changes)
    {
        // Create/update the materialized view document
        var statusView = new OrderStatusView
        {
            Id = order.Id,
            CustomerId = order.CustomerId,
            Status = order.Status,  // This becomes the partition key
            CreatedAt = order.CreatedAt,
            Total = order.Total
        };
        
        await ordersByStatusContainer.UpsertItemAsync(
            statusView,
            new PartitionKey(order.Status.ToString()),
            cancellationToken: cancellationToken
        );
    }
}

await processor.StartAsync();

Implementation - Java:

// Change Feed processor with Spring Boot
@Component
public class OrderStatusViewProcessor {
    
    @Autowired
    private CosmosAsyncContainer ordersByStatusContainer;
    
    public void startProcessor(CosmosAsyncContainer ordersContainer, 
                               CosmosAsyncContainer leaseContainer) {
        
        ChangeFeedProcessor processor = new ChangeFeedProcessorBuilder<Order>()
            .hostName("processor-1")
            .feedContainer(ordersContainer)
            .leaseContainer(leaseContainer)
            .handleChanges(this::handleChanges)
            .buildChangeFeedProcessor();
            
        processor.start().block();
    }
    
    private void handleChanges(List<Order> changes, ChangeFeedProcessorContext context) {
        for (Order order : changes) {
            OrderStatusView view = new OrderStatusView(
                order.getId(),
                order.getCustomerId(), 
                order.getStatus(),
                order.getCreatedAt(),
                order.getTotal()
            );
            
            ordersByStatusContainer.upsertItem(
                view,
                new PartitionKey(order.getStatus().getValue()),
                new CosmosItemRequestOptions()
            ).block();
        }
    }
}

Implementation - Python:

from azure.cosmos import CosmosClient
from azure.cosmos.aio import CosmosClient as AsyncCosmosClient
import asyncio

async def process_change_feed():
    """Process changes and update materialized view"""
    
    async with AsyncCosmosClient(endpoint, credential=key) as client:
        orders_container = client.get_database_client(db).get_container_client("orders")
        status_container = client.get_database_client(db).get_container_client("orders-by-status")
        
        # Read change feed
        async for changes in orders_container.query_items_change_feed():
            for order in changes:
                # Upsert to materialized view
                status_view = {
                    "id": order["id"],
                    "customerId": order["customerId"],
                    "status": order["status"],  # Partition key in target container
                    "createdAt": order["createdAt"],
                    "total": order["total"]
                }
                
                await status_container.upsert_item(
                    body=status_view,
                    partition_key=order["status"]
                )

Query the materialized view (single-partition!):

// Now this is a single-partition query - fast and cheap!
var query = ordersByStatusContainer.GetItemQueryIterator<OrderStatusView>(
    new QueryDefinition("SELECT * FROM c WHERE c.status = @status ORDER BY c.createdAt DESC")
        .WithParameter("@status", "Pending"),
    requestOptions: new QueryRequestOptions { PartitionKey = new PartitionKey("Pending") }
);

When to use this pattern:

Use Materialized Views WhenStick with Cross-Partition When
High-frequency admin queriesRare/occasional admin queries
Large dataset (100K+ docs)Small dataset (<10K docs)
Query latency is criticalLatency is acceptable
Consistent query patternsAd-hoc query patterns

Trade-offs:

BenefitCost
Fast single-partition queriesAdditional storage (duplicated data)
Predictable latencyChange Feed processor complexity
Better scalabilityEventual consistency (slight delay)
Lower RU cost per queryRU cost for writes to both containers

Key Points:

  • Change Feed provides reliable, ordered event stream of all document changes

  • Materialized views trade storage cost for query efficiency

  • Updates are eventually consistent (typically <1 second delay)

  • Use lease container to track processor progress (enables resume after failures)

  • Consider Azure Functions with Cosmos DB trigger for serverless implementation

  • Consider Global Secondary Index (GSI) implementation as alternative for automatic sync between containers with different partition keys.

Reference(s): Change feed in Azure Cosmos DB Global Secondary Indexes (GSI) in Azure Cosmos DB

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

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