Individual skill

cosmosdb-best-practices

Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage. Use when writing, reviewing, or refactoring code that interacts with Azure Cosmos DB, designing data models, optimizing queries, or implementing high-performance database operations. USE FOR: Cosmos DB NoSQL, partition key design, RU optimization, point reads, cross-partition queries, SDK singleton, CosmosClient, container modeling, change feed, bulk operations, vector search, full-text search, hierarchical partition keys, global distribution, autoscale throughput, indexing policy, DO NOT USE FOR: PostgreSQL, MySQL, MongoDB (non-Azure), DynamoDB, Cassandra, Azure SQL, Cosmos DB for PostgreSQL (vCore), Cosmos DB for MongoDB vCore, Azure DocumentDB, general SQL databases, Redis, Elasticsearch.

skills/cosmosdb-best-practices/SKILL.md

Read pinned source

Source commit 3ddc18fcd4d6fe0fae154f408395ff83c39495ee

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: Yes
Repository scan complete: No
Skill scan complete: No
Observed behavior: Network or broad shell
Last checked: Nov 4, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 62
Repository last updated: Nov 3, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

agent-skills Repository topic
azure-cosmos-db Repository topic
azure-cosmosdb Repository topic
best-practices Repository topic
mcp Repository topic
data Derived category
design Derived category
operations Derived category
writing Derived category
devops Derived category
data-databases Derived category
devops-containers Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

README.mddoc · 4,923 bytes
SKILL.mdcore · 21,031 bytes
SKILL.mdcore · 21,031 bytes
agents/openai.yamlasset · 310 bytes
metadata.jsonasset · 590 bytes
rules/_sections.mddoc · 3,085 bytes
rules/_template.mddoc · 1,039 bytes
rules/fts-add-index.mddoc · 1,976 bytes
rules/fts-define-policy.mddoc · 1,707 bytes
rules/fts-enable-capability.mddoc · 1,636 bytes
rules/fts-hybrid-queries.mddoc · 2,327 bytes
rules/fts-keyword-matching.mddoc · 2,209 bytes
rules/fts-relevance-ranking.mddoc · 1,459 bytes
rules/global-conflict-resolution.mddoc · 4,087 bytes
rules/global-consistency.mddoc · 3,962 bytes
rules/global-failover.mddoc · 3,804 bytes
rules/global-multi-region-write-antipattern.mddoc · 2,646 bytes
rules/global-multi-region.mddoc · 3,313 bytes
rules/global-read-regions.mddoc · 3,994 bytes
rules/global-zone-redundancy.mddoc · 3,576 bytes
rules/index-composite-direction.mddoc · 2,892 bytes
rules/index-composite.mddoc · 11,955 bytes
rules/index-exclude-unused.mddoc · 4,046 bytes
rules/index-lazy-consistent.mddoc · 3,363 bytes
rules/index-path-syntax.mddoc · 2,545 bytes
rules/index-range-vs-hash.mddoc · 3,956 bytes
rules/index-spatial.mddoc · 3,193 bytes
rules/model-avoid-2mb-limit.mddoc · 2,096 bytes
rules/model-denormalize-reads.mddoc · 12,537 bytes
rules/model-embed-related.mddoc · 2,528 bytes
rules/model-id-constraints.mddoc · 7,581 bytes
rules/model-json-serialization.mddoc · 6,175 bytes
rules/model-nesting-depth.mddoc · 3,421 bytes
rules/model-numeric-precision.mddoc · 3,324 bytes
rules/model-reference-large.mddoc · 2,313 bytes
rules/model-relationship-references.mddoc · 3,664 bytes
rules/model-schema-versioning.mddoc · 2,893 bytes
rules/model-ttl-expiration.mddoc · 3,174 bytes
rules/model-type-discriminator.mddoc · 3,583 bytes
rules/model-unique-keys.mddoc · 5,450 bytes
rules/monitoring-azure-monitor.mddoc · 4,531 bytes
rules/monitoring-diagnostic-logs.mddoc · 5,204 bytes
rules/monitoring-latency.mddoc · 4,303 bytes
rules/monitoring-ru-consumption.mddoc · 7,632 bytes
rules/monitoring-throttling.mddoc · 4,491 bytes
rules/partition-20gb-limit.mddoc · 2,893 bytes
rules/partition-avoid-hotspots.mddoc · 3,478 bytes
rules/partition-hierarchical.mddoc · 5,826 bytes
rules/partition-high-cardinality.mddoc · 2,234 bytes
rules/partition-immutable-key.mddoc · 1,812 bytes
rules/partition-key-length.mddoc · 2,892 bytes
rules/partition-query-patterns.mddoc · 2,747 bytes
rules/partition-rekey-migration.mddoc · 4,470 bytes
rules/partition-synthetic-keys.mddoc · 3,914 bytes
rules/pattern-ai-grounding-access.mddoc · 4,862 bytes
rules/pattern-background-task-writes.mddoc · 2,907 bytes
rules/pattern-change-feed-materialized-views.mddoc · 11,559 bytes
rules/pattern-efficient-ranking.mddoc · 6,053 bytes
rules/pattern-langgraph-agent-name-attribution.mddoc · 2,239 bytes
rules/pattern-langgraph-agent-routing-cosmosdb.mddoc · 4,690 bytes
rules/pattern-langgraph-async-cosmos-routing.mddoc · 3,286 bytes
rules/pattern-langgraph-async-cosmos-writes.mddoc · 2,951 bytes
rules/pattern-langgraph-chat-history-separate.mddoc · 3,431 bytes
rules/pattern-langgraph-fastapi-startup.mddoc · 3,146 bytes
rules/pattern-langgraph-interrupt-human.mddoc · 3,745 bytes
rules/pattern-langgraph-multi-agent.mddoc · 4,332 bytes
rules/pattern-langgraph-resume-checkpoint.mddoc · 3,213 bytes
rules/pattern-service-layer-relationships.mddoc · 4,878 bytes
rules/query-aggregate-single-pass.mddoc · 2,722 bytes
rules/query-avoid-cross-partition.mddoc · 4,364 bytes
rules/query-avoid-scans.mddoc · 2,569 bytes
rules/query-distinct-keyword.mddoc · 2,315 bytes
rules/query-latest-by-timestamp.mddoc · 2,223 bytes
rules/query-olap-detection.mddoc · 5,064 bytes
rules/query-order-filters.mddoc · 4,810 bytes
rules/query-pagination.mddoc · 7,846 bytes
rules/query-parameterize.mddoc · 3,833 bytes
rules/query-point-reads.mddoc · 9,916 bytes
rules/query-top-literal.mddoc · 1,928 bytes
rules/query-use-projections.mddoc · 5,660 bytes
rules/sdk-async-api.mddoc · 3,291 bytes
rules/sdk-availability-strategy.mddoc · 5,405 bytes
rules/sdk-circuit-breaker.mddoc · 8,576 bytes
rules/sdk-conditional-create-etag.mddoc · 2,867 bytes
rules/sdk-connection-mode.mddoc · 2,969 bytes
rules/sdk-continuation-token-null-guard.mddoc · 3,308 bytes
rules/sdk-diagnostics.mddoc · 6,822 bytes
rules/sdk-dotnet-cosmos-package-id.mddoc · 1,844 bytes
rules/sdk-dotnet-namespace-collision.mddoc · 2,865 bytes
rules/sdk-emulator-ssl.mddoc · 15,631 bytes
rules/sdk-etag-concurrency.mddoc · 9,779 bytes
rules/sdk-excluded-regions.mddoc · 4,979 bytes
rules/sdk-go-partition-key-metadata.mddoc · 3,061 bytes
rules/sdk-ingestion-rate-control.mddoc · 8,892 bytes
rules/sdk-java-content-response.mddoc · 8,427 bytes
rules/sdk-java-cosmos-config.mddoc · 10,314 bytes
rules/sdk-java-spring-boot-versions.mddoc · 5,047 bytes
rules/sdk-langchain-async-checkpointer.mddoc · 2,882 bytes
rules/sdk-langchain-cosmosdb-saver.mddoc · 2,612 bytes
rules/sdk-langchain-js-chat-history.mddoc · 3,480 bytes
rules/sdk-langchain-js-embedding-model.mddoc · 2,910 bytes
rules/sdk-langchain-js-filter-injection.mddoc · 3,973 bytes
rules/sdk-langchain-js-fulltext-prerequisites.mddoc · 3,840 bytes
rules/sdk-langchain-js-managed-identity.mddoc · 2,787 bytes
rules/sdk-langchain-js-search-types.mddoc · 2,753 bytes
rules/sdk-langchain-js-semantic-cache.mddoc · 3,037 bytes
rules/sdk-langchain-js-vectorstore-init.mddoc · 2,825 bytes
rules/sdk-langchain-mcp-persistent-session.mddoc · 3,508 bytes
rules/sdk-langchain-mcp-tool-content-format.mddoc · 1,982 bytes
rules/sdk-langgraph-mcp-tool-filtering.mddoc · 2,653 bytes
rules/sdk-local-dev-config.mddoc · 5,614 bytes
rules/sdk-newtonsoft-dependency.mddoc · 4,486 bytes
rules/sdk-patch-counter-increment.mddoc · 3,985 bytes
rules/sdk-preferred-regions.mddoc · 3,229 bytes
rules/sdk-python-async-deps.mddoc · 1,366 bytes
rules/sdk-python-client-kwargs.mddoc · 3,494 bytes
rules/sdk-request-options-per-call.mddoc · 3,982 bytes
rules/sdk-retry-429.mddoc · 3,786 bytes
rules/sdk-serialization-enums.mddoc · 4,180 bytes
rules/sdk-singleton-client.mddoc · 6,282 bytes
rules/sdk-spring-data-annotations.mddoc · 4,847 bytes
rules/sdk-spring-data-repository.mddoc · 3,532 bytes
rules/security-continuous-backup.mddoc · 2,304 bytes
rules/security-disable-local-auth.mddoc · 2,294 bytes
rules/security-managed-identity.mddoc · 3,387 bytes
rules/security-network-restrict.mddoc · 2,197 bytes
rules/security-private-endpoint-dns.mddoc · 9,533 bytes
rules/security-rbac-least-privilege.mddoc · 3,154 bytes
rules/throughput-autoscale.mddoc · 3,753 bytes
rules/throughput-burst.mddoc · 2,737 bytes
rules/throughput-container-vs-database.mddoc · 3,432 bytes
rules/throughput-idle-container-review.mddoc · 3,202 bytes
rules/throughput-right-size.mddoc · 3,139 bytes
rules/throughput-serverless-migration.mddoc · 3,106 bytes
rules/throughput-serverless.mddoc · 2,714 bytes
rules/throughput-ttl-stale-data.mddoc · 3,040 bytes
rules/tooling-cosmosdb-shell-setup.mddoc · 4,783 bytes
rules/tooling-cosmosdb-shell-target.mddoc · 6,011 bytes
rules/tooling-cosmosdb-shell-writes.mddoc · 8,461 bytes
rules/tooling-emulator-setup.mddoc · 1,472 bytes
rules/tooling-vscode-extension.mddoc · 1,559 bytes
rules/vector-distance-query.mddoc · 4,892 bytes
rules/vector-embedding-policy.mddoc · 3,866 bytes
rules/vector-enable-feature.mddoc · 3,098 bytes
rules/vector-index-type.mddoc · 6,926 bytes
rules/vector-normalize-embeddings.mddoc · 8,779 bytes
rules/vector-repository-pattern.mddoc · 13,226 bytes

Read excerpt


# Azure Cosmos DB Best Practices

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

Before answering, read the linked rule files relevant to the user's question.
The quick reference below is an index, not the full guidance: SDK APIs, limits,
configuration prerequisites, and caveats live in the rule bodies. Use the
language-specific integration rule when one exists rather than substituting a
generic pattern. Keep answers concise, but include the constraints that make the
recommendation correct for the user's scenario.

## When to Apply

Reference these guidelines when: