Cosmosdb Datamodeling

Azure Cosmos DB NoSQL data modeling

Gather application requirements, access patterns, volumetrics, concurrency, and relationship constraints; maintain cosmosdb_requirements.md during discovery; then create cosmosdb_data_model.md with a justified Azure Cosmos DB for NoSQL container, partition-key, indexing, and denormalization design.

When to invoke

• "Design a Cosmos DB NoSQL data model for this app."
• "Help choose containers and partition keys from our access patterns."
• "Create cosmosdb_requirements.md and cosmosdb_data_model.md."
• "Review whether these entities should be embedded or separated."
• "We have massive Cosmos DB write volume and need a data model."

Prerequisites and context

• Work from the user's domain, entities, relationships, access patterns, RPS, latency SLOs, consistency needs, document size, retention, and geographic distribution.
• Maintain two files in the working repository: cosmosdb_requirements.md as the live scratchpad and cosmosdb_data_model.md as the final deliverable.
• Ask one question at a time when possible, and at most three related questions.
• Read references/extended-guide.md when the main skill does not contain enough detail for advanced Cosmos DB modeling decisions.

Discovery rules

Update cosmosdb_requirements.md after every user message that adds information. Capture evolving thoughts, uncertain assumptions, and design considerations instead of waiting for a final answer.

For massive scale signals such as >10k writes/sec, several million records in a short period, or the phrase "massive scale", immediately ask about:

1. Data binning or chunking strategies: can individual records be grouped into chunks?
2. Write reduction: what is the minimum number of actual write operations, and can work be batched?
3. Physical partition impact: how will total data size affect cross-partition query costs?

Every access pattern must have RPS. If the user does not know, estimate from business context and label the value as an assumption.

Requirements artifact

Create or update cosmosdb_requirements.md with this concrete structure:

# Azure Cosmos DB NoSQL Modeling Session

## Application Overview
- **Domain**: <domain>
- **Key Entities**: <entity list and relationships such as User (1:M) Orders>
- **Business Context**: <rules, constraints, compliance>
- **Scale**: <concurrent users, document sizes, retention, total requests/second>
- **Geographic Distribution**: <single region, multi-region reads, multi-region writes>

## Access Patterns Analysis
| Pattern # | Description | RPS (Peak and Average) | Type | Attributes Needed | Key Requirements | Design Considerations | Status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | Get user profile by user ID when the user logs into the app | 500 RPS | Read | userId, name, email, createdAt | <50ms latency | Simple point read with id and partition key | Yes |
| 2 | Create new user account when the user is on the sign up page | 50 RPS | Write | userId, name, email, hashedPassword | Strong consistency | Consider unique key constraints for email | Pending |

## Entity Relationships Deep Dive
- **User → Orders**: 1:Many (avg 5 orders per user, max 1000)
- **Order → OrderItems**: 1:Many (avg 3 items per order, max 50)
- **Product → OrderItems**: 1:Many (popular products in many orders)
- **Products and Categories**: Many:Many

## Enhanced Aggregate Analysis
### <Entity1 + Entity2> Container Item Analysis
- **Access Correlation**: <% requiring both entities>
- **Query Patterns**: Entity1 only, Entity2 only, and both together percentages
- **Size Constraints**: Combined max size in MB and growth pattern
- **Update Patterns**: Independent or related update frequencies
- **Decision**: Single Document, Multi-Document Container, or Separate Containers
- **Justification**: <reasoning>

## Container Consolidation Analysis
| Parent | Child | Relationship | Access Overlap | Consolidation Decision | Justification |
| --- | --- | --- | --- | --- | --- |
| <Parent> | <Child> | 1:Many | <overlap> | Consolidate/Separate | <why> |

## Design Considerations (Subject to Change)
- **Hot Partition Concerns**: <analysis>
- **Large fan-out with Many Physucal partitions based on total Datasize Concerns**: <analysis>
- **Cross-Partition Query Costs**: <trade-offs>
- **Indexing Strategy**: <composite indexes, included paths, excluded paths>
- **Multi-Document Opportunities**: <30-70% correlation candidates>
- **Multi-Entity Query Patterns**: <related retrievals>
- **Denormalization Ideas**: <duplicated attributes>
- **Global Distribution**: <write regions and consistency levels>

## Validation Checklist
- [ ] Application domain and scale documented
- [ ] All entities and relationships mapped
- [ ] Aggregate boundaries identified based on access patterns
- [ ] Identifying relationships checked for consolidation opportunities
- [ ] Container consolidation analysis completed
- [ ] Every access pattern has: RPS (avg/peak), latency SLO, consistency level, expected result size, document size band
- [ ] Write pattern exists for every read pattern (and vice versa) unless USER explicitly declines
- [ ] Hot partition risks evaluated
- [ ] Consolidation framework applied; candidates reviewed
- [ ] Design considerations captured (subject to final validation)

Modeling decisions

Consolidate when access overlap is >50%, the relationship is natural parent-child, size is bounded, and an identifying relationship exists. Keep separate when access overlap is <30%, growth is unbounded, or operations must scale independently.

Procedure

1. Capture application overview, entities, business context, scale, geographic distribution, and compliance constraints in cosmosdb_requirements.md.
2. Stay in access-pattern discovery until the user confirms all reads and writes are captured. Ask, "Do you have any other access patterns to discuss? I see we have a user login access pattern but no pattern to create users. Should we add one?"
3. For each access pattern, record average/peak RPS, read/write type, attributes, latency SLO, consistency level, result size, document size band, and status.
4. Analyze aggregates, identifying relationships, access correlation, update coupling, size constraints, hot partitions, cross-partition query costs, indexing, and denormalization.
5. Only after the user confirms access patterns are complete, create cosmosdb_data_model.md with final container designs and justifications.
6. Group indexes with the containers they belong to; do not create a detached indexing section that loses container context.

Final deliverable

Create cosmosdb_data_model.md only after confirmation:

# Azure Cosmos DB NoSQL Data Model

## Design Philosophy & Approach
<aggregate-oriented design principles and request-unit rationale>

## Aggregate Design Decisions
<why data was grouped together, split, or duplicated>

## Container Designs
### <Container name>
- **Purpose**: <what it stores>
- **Document Types**: <type discriminator values if Multi-Document Container>
- **Partition Key**: <path and why>
- **ID Strategy**: <id shape>
- **Items**: <example document summaries>
- **Indexes**: <included paths, excluded paths, composite indexes grouped here>
- **Served Access Patterns**: <pattern IDs>
- **Trade-offs**: <hot partition, cross-partition, transaction, consistency notes>

Progressive disclosure and bundled resources

• references/extended-guide.md: deeper Cosmos DB modeling guidance for aggregate, partition-key, indexing, and scale decisions.

Compatibility vocabulary

Preserve these legacy terms, API names, command placeholders, and literal phrases when applying or migrating this skill:

• AP31
• CRITICAL
• Container/Separate
• Document/Multi-Document
• EVERY
• FILE
• IMMEDIATELY
• Independent/Related
• MANAGEMENT
• MASSIVE
• MOST
• MUST
• No/Yes/Yes
• SCALE
• WARNING
• artifacts_produced
• binning/chunking
• by-step
• e-commerce
• last_updated
• progressive-disclosure
• use-case
• user_id
• volume/size
• UserOrders

Output template

## Cosmos DB data modeling result

**Status:** requirements-updated | model-created | blocked
**Files changed:** `cosmosdb_requirements.md`, `cosmosdb_data_model.md`

### Requirements captured
| Area | Status | Evidence |
| --- | --- | --- |
| Access patterns | <complete/incomplete> | <count and missing fields> |
| Scale and RPS | <complete/incomplete> | <avg/peak RPS notes> |
| Relationships | <complete/incomplete> | <entities and cardinality> |

### Design summary
| Container | Partition key | Document types | Main access patterns | Key trade-off |
| --- | --- | --- | --- | --- |
| <name> | <partition key> | <types> | <pattern IDs> | <trade-off> |

### Open questions
- <question or none>

Quality gate

• cosmosdb_requirements.md was updated after every new user-provided fact.
• Every access pattern includes RPS, latency SLO, consistency, result size, and document size band.
• Every read has a matching write or an explicit user-declined write pattern.
• Massive-scale workloads triggered binning, write-reduction, and physical-partition questions.
• Aggregates were judged by access correlation, size, update coupling, and identifying relationships.
• cosmosdb_data_model.md was created only after the user confirmed discovery was complete.
• Index definitions are grouped under their owning containers.