azurecosmosdb/cosmosdb-agent-kitMIT142 files

Cosmosdb Best Practices

Name: Cosmosdb Best Practices
Availability: InStock
Author: azurecosmosdb

Use this skill View repository View on skills.sh

Specification

Skill ID: azurecosmosdb/cosmosdb-agent-kit/cosmosdb-best-practices
Publisher: azurecosmosdb
Repository: cosmosdb-agent-kit
Installs: 0
Files: 142
License: MIT
Synced: Sep 23, 2026

How to use it

Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.

azurecosmosdb/cosmosdb-agent-kit/cosmosdb-best-practicesInstalls these files

README.md
SKILL.md
agents/openai.yaml
metadata.json
rules/_sections.md
rules/_template.md
rules/fts-add-index.md
rules/fts-define-policy.md
rules/fts-enable-capability.md
rules/fts-hybrid-queries.md
rules/fts-keyword-matching.md
rules/fts-relevance-ranking.md
rules/global-conflict-resolution.md
rules/global-consistency.md
rules/global-failover.md
rules/global-multi-region-write-antipattern.md
rules/global-multi-region.md
rules/global-read-regions.md
rules/global-zone-redundancy.md
rules/index-composite-direction.md
rules/index-composite.md
rules/index-exclude-unused.md
rules/index-lazy-consistent.md
rules/index-path-syntax.md
rules/index-range-vs-hash.md
rules/index-spatial.md
rules/model-avoid-2mb-limit.md
rules/model-denormalize-reads.md
rules/model-embed-related.md
rules/model-id-constraints.md
rules/model-json-serialization.md
rules/model-nesting-depth.md
rules/model-numeric-precision.md
rules/model-reference-large.md
rules/model-relationship-references.md
rules/model-schema-versioning.md
rules/model-ttl-expiration.md
rules/model-type-discriminator.md
rules/monitoring-azure-monitor.md
rules/monitoring-diagnostic-logs.md
rules/monitoring-latency.md
rules/monitoring-ru-consumption.md
rules/monitoring-throttling.md
rules/partition-20gb-limit.md
rules/partition-avoid-hotspots.md
rules/partition-hierarchical.md
rules/partition-high-cardinality.md
rules/partition-immutable-key.md
rules/partition-key-length.md
rules/partition-query-patterns.md
rules/partition-rekey-migration.md
rules/partition-synthetic-keys.md
rules/pattern-ai-grounding-access.md
rules/pattern-background-task-writes.md
rules/pattern-change-feed-materialized-views.md
rules/pattern-efficient-ranking.md
rules/pattern-langgraph-agent-name-attribution.md
rules/pattern-langgraph-agent-routing-cosmosdb.md
rules/pattern-langgraph-async-cosmos-routing.md
rules/pattern-langgraph-async-cosmos-writes.md
rules/pattern-langgraph-chat-history-separate.md
rules/pattern-langgraph-fastapi-startup.md
rules/pattern-langgraph-interrupt-human.md
rules/pattern-langgraph-multi-agent.md
rules/pattern-langgraph-resume-checkpoint.md
rules/pattern-service-layer-relationships.md
rules/query-aggregate-single-pass.md
rules/query-avoid-cross-partition.md
rules/query-avoid-scans.md
rules/query-distinct-keyword.md
rules/query-latest-by-timestamp.md
rules/query-olap-detection.md
rules/query-order-filters.md
rules/query-pagination.md
rules/query-parameterize.md
rules/query-point-reads.md
rules/query-top-literal.md
rules/query-use-projections.md
rules/sdk-async-api.md
rules/sdk-availability-strategy.md
rules/sdk-circuit-breaker.md
rules/sdk-conditional-create-etag.md
rules/sdk-connection-mode.md
rules/sdk-continuation-token-null-guard.md
rules/sdk-diagnostics.md
rules/sdk-dotnet-cosmos-package-id.md
rules/sdk-dotnet-namespace-collision.md
rules/sdk-emulator-ssl.md
rules/sdk-etag-concurrency.md
rules/sdk-excluded-regions.md
rules/sdk-go-partition-key-metadata.md
rules/sdk-ingestion-rate-control.md
rules/sdk-java-content-response.md
rules/sdk-java-cosmos-config.md
rules/sdk-java-spring-boot-versions.md
rules/sdk-langchain-async-checkpointer.md
rules/sdk-langchain-cosmosdb-saver.md
rules/sdk-langchain-js-chat-history.md
rules/sdk-langchain-js-embedding-model.md
rules/sdk-langchain-js-filter-injection.md
rules/sdk-langchain-js-fulltext-prerequisites.md
rules/sdk-langchain-js-managed-identity.md
rules/sdk-langchain-js-search-types.md
rules/sdk-langchain-js-semantic-cache.md
rules/sdk-langchain-js-vectorstore-init.md
rules/sdk-langchain-mcp-persistent-session.md
rules/sdk-langchain-mcp-tool-content-format.md
rules/sdk-langgraph-mcp-tool-filtering.md
rules/sdk-local-dev-config.md
rules/sdk-newtonsoft-dependency.md
rules/sdk-patch-counter-increment.md
rules/sdk-preferred-regions.md
rules/sdk-python-async-deps.md
rules/sdk-python-client-kwargs.md
rules/sdk-request-options-per-call.md
rules/sdk-retry-429.md
rules/sdk-serialization-enums.md
rules/sdk-singleton-client.md
rules/sdk-spring-data-annotations.md
rules/sdk-spring-data-repository.md
rules/security-continuous-backup.md
rules/security-disable-local-auth.md
rules/security-managed-identity.md
rules/security-network-restrict.md
rules/security-private-endpoint-dns.md
rules/security-rbac-least-privilege.md
rules/throughput-autoscale.md
rules/throughput-burst.md
rules/throughput-container-vs-database.md
rules/throughput-idle-container-review.md
rules/throughput-right-size.md
rules/throughput-serverless-migration.md
rules/throughput-serverless.md
rules/throughput-ttl-stale-data.md
rules/tooling-emulator-setup.md
rules/tooling-vscode-extension.md
rules/vector-distance-query.md
rules/vector-embedding-policy.md
rules/vector-enable-feature.md
rules/vector-index-type.md
rules/vector-normalize-embeddings.md
rules/vector-repository-pattern.md

What this skill tells the agent

Azure Cosmos DB Best Practices

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

When to Apply

Reference these guidelines when:

Designing data models for Cosmos DB
Choosing partition keys
Writing or optimizing queries
Implementing SDK patterns
Using the Cosmos DB Emulator for local development
Inspecting or managing Cosmos DB data with developer tooling
Implementing vector search or RAG features on Cosmos DB
Reviewing code for performance issues
Configuring throughput and scaling
Building globally distributed applications

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Data Modeling	CRITICAL	`model-`
2	Partition Key Design	CRITICAL	`partition-`
3	Query Optimization	HIGH	`query-`
4	SDK Best Practices	HIGH	`sdk-`
5	Indexing Strategies	MEDIUM-HIGH	`index-`
6	Throughput & Scaling	MEDIUM	`throughput-`
7	Global Distribution	MEDIUM	`global-`
8	Monitoring & Diagnostics	LOW-MEDIUM	`monitoring-`
9	Design Patterns	HIGH	`pattern-`
10	Developer Tooling	MEDIUM	`tooling-`
11	Vector Search	HIGH	`vector-`

Quick Reference

1. Data Modeling (CRITICAL)

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

2. Partition Key Design (CRITICAL)

partition-high-cardinality - Choose high-cardinality partition keys
partition-avoid-hotspots - Distribute writes evenly
partition-hierarchical - Use hierarchical partition keys for flexibility; order levels broad→narrow
partition-query-patterns - Align partition key with query patterns
partition-synthetic-keys - Create synthetic keys when needed
partition-key-length - Respect partition key value length limits
partition-immutable-key - Choose immutable properties as partition keys
partition-20gb-limit - Plan for 20GB logical partition limit
partition-rekey-migration - Re-key a misaligned container with the Change partition key feature

3. Query Optimization (HIGH)

query-aggregate-single-pass - Compute min/max/avg with one scoped aggregate query
query-avoid-cross-partition - Minimize cross-partition queries
query-use-projections - Project only needed fields; prefer dedicated result types for projections
query-pagination - Use continuation tokens for pagination
query-avoid-scans - Avoid full container scans
query-parameterize - Use parameterized queries
query-order-filters - Order filters by selectivity
query-top-literal - Use literal integers for TOP, never parameters
query-latest-by-timestamp - Query "latest" documents with explicit ORDER BY and TOP 1
query-olap-detection - Detect and redirect analytical queries away from transactional containers
query-point-reads - Use point reads (ReadItem) instead of queries when id and partition key are known

4. SDK Best Practices (HIGH)

sdk-singleton-client - Reuse CosmosClient as singleton
sdk-async-api - Use async APIs for throughput
sdk-retry-429 - Handle 429s with retry-after
sdk-connection-mode - Use Direct mode for production
sdk-preferred-regions - Configure preferred regions
sdk-excluded-regions - Exclude regions experiencing issues
sdk-availability-strategy - Configure availability strategy for resilience
sdk-circuit-breaker - Use circuit breaker for fault tolerance
sdk-diagnostics - Log diagnostics for troubleshooting
sdk-serialization-enums - Serialize enums as strings not integers
sdk-emulator-ssl - Configure SSL and connection mode for Cosmos DB Emulator
sdk-ifnonematch-create - Use setIfNoneMatchETag("*") on createItem to reject duplicates atomically (409 on conflict)
sdk-no-shared-request-options - Never reuse a CosmosItemRequestOptions instance across multiple createItem calls — SDK mutates it internally, causing wrong partition key on second call
sdk-patch-incr - Use CosmosPatchOperations.incr() for atomic counter increments — no read RU, no ETag conflict cycle
sdk-bypage-empty-token - Guard against empty-string continuation tokens before calling byPage() — pass null for first page, never ""
sdk-etag-concurrency - Use ETags for optimistic concurrency on read-modify-write operations
sdk-java-content-response - Enable content response on write operations (Java)
sdk-java-cosmos-config - Configure Cosmos DB initialization correctly in Spring Boot
sdk-java-spring-boot-versions - Match Java version to Spring Boot requirements
sdk-local-dev-config - Configure local development to avoid cloud conflicts
sdk-dotnet-cosmos-package-id - Use Microsoft.Azure.Cosmos, not the abandoned Azure.Cosmos v4-preview package
sdk-newtonsoft-dependency - Explicitly reference Newtonsoft.Json package
sdk-python-async-deps - Include aiohttp when using Python async SDK
sdk-spring-data-annotations - Annotate entities for Spring Data Cosmos
sdk-spring-data-repository - Use CosmosRepository correctly and handle Iterable return types

Use this skill in a project

Open any RiverX project, search the Skills panel for azurecosmosdb/cosmosdb-agent-kit/cosmosdb-best-practices, and install it in one click.

Use this skill