# Cosmos DB application design

## What people get wrong

- They start with entity diagrams instead of access patterns. Cosmos DB data modeling starts from how the application reads and writes.
- They choose a human-friendly partition key that creates hot logical partitions.
- They query where they could point-read by ID and partition key.
- They over-index every property and then wonder why writes are expensive.
- They assume transactional batch crosses partition keys. It does not.

## Officially grounded service shape

Microsoft Learn explains that RUs are a normalized measure affected by document size, indexing, consistency, query shape, and operations. Point reads using item ID plus partition key are the most efficient reads. Transactional batch provides ACID semantics for operations sharing the same logical partition key. In multi-region accounts, throughput is provisioned in each region and consistency choices affect read throughput.

## Non-negotiable design rules

1. Design containers around dominant access patterns, not just entity type.
2. Choose partition keys with high cardinality, even request distribution, growth headroom, and locality for transactions or common queries.
3. Prefer point reads for hot paths. If a query is required, keep it partition-scoped where possible.
4. Treat document size and indexed properties as write-cost drivers.
5. State consistency requirements explicitly for each user flow.
6. Use transactional batch only when all operations share a logical partition key and fit documented limits.
7. Measure request charge and query metrics before asserting cost or performance.

## Minimal safe implementation flow

1. List top user flows and background jobs with expected read/write frequency.
2. Define documents, IDs, partition keys, and denormalization based on those flows.
3. Map each critical read to point read, partition-scoped query, or cross-partition query.
4. Define indexing policy from actual filters, sort orders, and projections.
5. Decide consistency per flow, not globally by habit.
6. Validate with sample data, realistic distribution, request charge logging, query metrics, and failure tests.
7. Document migration and rollback for existing containers.

## High-risk assumptions to kill

- A partition key that looks logical to humans is unsafe until cardinality, storage growth, and request distribution are tested against real access patterns.
- Querying by ID plus partition-key equality is not the same as a point read; hot paths should use SDK point-read APIs where possible.
- Cross-partition queries can be acceptable for low-volume paths, but they are not free and must carry measured RU and latency evidence.
- Transactional batch is not a cross-partition transaction; every operation must share the same logical partition key.
- Stronger consistency can change read cost and throughput behavior, so consistency must be selected per user flow, not by default habit.

## Safe command/code verification targets

- Review repository code for point reads that pass both item ID and partition key on hot paths.
- Check query builders for partition-key filters, continuation-token handling, max item count, and diagnostics or request-charge logging.
- Inspect container/IaC definitions for partition key path, throughput mode, indexing policy, unique keys, TTL, and analytical/change-feed assumptions.
- Verify transactional batch code constructs one batch per logical partition key and fails closed when mixed keys appear.
- Require load-test or fixture evidence that reports request charge, output count, retrieved count, latency, and retry behavior for representative flows.

## Safe verification targets

- Candidate partition-key distribution and top hot-key risks.
- Request charge for representative create, replace, patch, delete, point read, and query operations.
- Query metrics showing index utilization, document load, output count, and scan behavior.
- Transactional batch operation count, payload size, and single-partition proof.
- SDK retry, timeout, connection mode, and diagnostics logging behavior.

## When to push back

Push back when the user wants a schema without access patterns, a partition key without cardinality proof, a critical cross-partition query, a cross-partition transaction, or an RU estimate with no measurement plan.

# MCP and evidence path for Cosmos DB application design

Use Microsoft Learn documentation through the user's configured documentation MCP as the first grounding path for Azure service behavior. This file defines evidence boundaries; it must not imply that documentation proves the user's tenant, subscription, RBAC, quotas, deployed resources, or production readiness.

## Evidence ladder

1. `docs_only`: Microsoft Learn documentation and official architecture guidance. Use for documented behavior, caveats, and safe review criteria.
2. `sampled_read_only`: configured-environment evidence from read-only tools, if available and explicitly scoped. Use only for the sampled resource/time window.
3. `user_supplied`: sanitized outputs, IaC, diagrams, or metrics provided by the user. Treat as unverified unless independently checked.
4. `mutation_ready`: documentation plus current-state evidence plus explicit approval, blast-radius statement, and rollback path.

## Rules

- Do not expose environment-specific implementation details in committed docs or user-facing guidance.
- Do not ask for credentials, tokens, tenant identifiers, subscription identifiers, connection strings, private keys, customer data, or raw secrets.
- If current-state evidence was not sampled, say `not sampled`; do not imply it.
- If evidence is representative or partial, say so. A sample does not prove broad regional availability or production readiness.
- Prefer read-only evidence before mutation planning. Stop for approval before write operations.

## Final-answer evidence language

Use phrases like:

- "Based on Microsoft Learn documentation..."
- "Configured-environment evidence was not sampled in this review."
- "The following is an inference from the provided configuration, not proven live state."
- "This recommendation is mutation-ready only after explicit approval and rollback review."

# Official sources for Azure Cosmos DB Application Developer

Use Microsoft Learn documentation through the user's configured documentation MCP before recommending data models or access patterns. Documentation proves documented Cosmos DB behavior; it does not prove the user's workload distribution, partition-key quality, RU budget, indexes, consistency setting, or latency profile.

## Primary Microsoft Learn sources

| Source | Review implication |
| --- | --- |
| [Partitioning and horizontal scaling in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning) | Partition key choice is a design-time scalability decision; require even distribution and access-pattern alignment. |
| [Model and partition data in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/modeling-data) | Use for embedding vs referencing, entity boundaries, denormalization, and query-driven document design. |
| [Understand request units consumption](https://learn.microsoft.com/en-us/azure/cosmos-db/understand-request-unit-consumption) | Ground RU costs in document size, indexing, consistency, query shape, and diagnostics. |
| [Request Units in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/request-units) | Use for provisioned throughput, multi-region RU behavior, and consistency tradeoffs. |
| [Consistency levels](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels) | Use for correctness and latency tradeoffs in read semantics. |
| [Transactional batch operations](https://learn.microsoft.com/en-us/azure/cosmos-db/transactional-batch) | Use for ACID operations scoped to the same logical partition key and batch limits. |
| [Optimize request cost for reads and writes](https://learn.microsoft.com/en-us/azure/cosmos-db/optimize-cost-reads-writes) | Use for point reads, query tuning, indexing, and request-charge checks. |
| [Architecture best practices for Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db) | Use for Well-Architected design tradeoffs across reliability, cost, performance, security, and operations. |

## Source-grounding rules

- Do not approve a partition key without access-pattern evidence.
- Do not recommend joins or cross-partition queries as the default path.
- Treat RU estimates as workload-dependent; require measured `RequestCharge` or metrics for precision.
- Keep API scope explicit: this skill defaults to Azure Cosmos DB for NoSQL unless the user names another API.

# Safety checklist for Azure Cosmos DB Application Developer

## Non-negotiable gates

- Never ask for account keys, connection strings, customer documents, full database dumps, tenant identifiers, subscription identifiers, or private data.
- Do not recommend a partition key without read/write access-pattern, cardinality, growth, and hot-key analysis.
- Do not recommend broad cross-partition scans as the normal path for high-volume user flows.
- Do not present RU cost as fixed without measured request charge and workload context.
- Require explicit approval before changing indexing policy, partition strategy, TTL, consistency, throughput, SDK retry policy, or data shape in existing workloads.

## High-risk assumptions to kill

- "We can model it like a relational database." Cosmos DB design is query and partition driven.
- "More RUs will fix the design." It can hide partition or query defects and increase cost.
- "Transactional batch works across arbitrary documents." It is scoped to operations with the same logical partition key.
- "Strong consistency is always safer." It can reduce throughput and increase latency; correctness requirements must justify it.
- "Index everything." Indexing helps queries but increases write RU consumption.

## Evidence labels

- `docs_only`: Microsoft Learn guidance only.
- `design_review`: user-supplied schema/API/access-pattern design reviewed, not measured.
- `measured_request`: request charge, query metrics, or diagnostics were provided or sampled.
- `mutation_ready`: change scope, backfill/migration, rollback, and approval are documented.

## Minimum safe evidence

- API surface, container purpose, entity types, expected document sizes, and growth.
- Top read and write access patterns with frequency, latency, and consistency requirements.
- Candidate partition keys with cardinality, distribution, hot-key risk, and transactional grouping needs.
- Query shapes, point-read opportunities, indexing needs, and expected RU budget.
- Migration/backfill strategy for existing containers.

# Workflow and output contract for Azure Cosmos DB Application Developer

## Minimal safe workflow

1. Classify the task: greenfield model, partition-key review, query design, transactional batch, SDK behavior, consistency, or change-feed design.
2. Ground the answer in Microsoft Learn through the user's configured documentation MCP.
3. Capture workload evidence: API type, entities, access patterns, data size, consistency needs, RU budget, and growth.
4. Stress test partition keys: cardinality, distribution, hot keys, transaction grouping, locality, and future access patterns.
5. Stress test query design: point reads first, partition-scoped queries, projections, index policy, pagination, and diagnostics.
6. Stress test correctness: consistency level, optimistic concurrency, transactional batch scope, idempotency, and change feed behavior.
7. Return concrete design guidance with risks, unknowns, and measurement plan.

## Output contract

```markdown
## Verdict
<recommended | conditional | not recommended | docs-only advisory>

## Evidence level
- Documentation: <sources used>
- Workload evidence: <design_review | measured_request | not provided>

## Design assessment
1. <finding> — Evidence: <docs_only|design_review|measured_request|inference>

## Partition and query decision
- Partition key: <recommendation or blocker>
- Access pattern fit: <summary>

## Safe next actions
- <measurement or design step>
```

## Pushback triggers

Push back on vague partition keys, relational normalization by default, fan-out queries on critical paths, unmeasured RU claims, cross-partition transaction assumptions, or consistency choices with no business correctness requirement.