# DynamoDB Access Patterns and Capacity Guide

Use this reference for DynamoDB table design, partition/sort keys, GSIs/LSIs, hot partitions, capacity mode, adaptive capacity, TTL, streams, global tables, transactions, DAX, and cost/performance reviews.

## What people get wrong

The lazy story is:

> Pick a partition key and add GSIs when queries need them.

Wrong. DynamoDB design starts with access patterns, cardinality, item size, write distribution, consistency needs, and growth model. Indexes are not a rescue plan for unknown queries.

Common bad assumptions:

- High-cardinality key always avoids hot partitions.
- Adaptive capacity fixes bad key design.
- Scans are acceptable until scale arrives.
- On-demand capacity eliminates throttling and cost planning.
- GSI backfill is operationally harmless.
- Global tables solve DR without conflict and latency tradeoffs.

## DynamoDB-specific failure modes

- Partition key concentrates reads/writes on tenant, status, date, or celebrity keys.
- Sort key does not support required range, prefix, ordering, or uniqueness patterns.
- GSI projection/backfill doubles write cost or throttles production.
- LSI item collection limits or large items break growth assumptions.
- TTL deletion timing is treated as immediate business logic.
- Transactions, conditional writes, streams, and idempotency are not modeled for retries.

## Minimum safe workflow

1. List concrete access patterns: operation, key condition, filter, consistency, frequency, latency, and expected cardinality.
2. Model entities and item collections against partition/sort keys before proposing tables/indexes.
3. Check write/read distribution, hot-key risk, item size, projected growth, and capacity mode.
4. Review indexes: GSI/LSI keys, projection, sparse behavior, backfill risk, and query shapes.
5. Validate operational controls: autoscaling/on-demand, alarms, Contributor Insights, TTL, streams, backups, and global tables.
6. Estimate cost and failure mode for peak traffic, backfills, retries, and scans.
7. State what cannot be proven without production traffic or representative workload tests.

## Verification targets

- access pattern matrix with key condition expressions, not just entity names
- table partition/sort keys, item collection examples, GSI/LSI definitions, projections, and sparse-index behavior
- CloudWatch metrics: throttles, consumed capacity, account/table limits, latency, system errors, and hot key signals
- Contributor Insights, adaptive capacity symptoms, split-for-heat context, and key distribution evidence
- capacity mode, autoscaling targets, reserved capacity, on-demand cost, backfill plan, and alarms
- TTL, streams, transactions, conditional writes, DAX, global tables, PITR/backups, and restore testing

## When to push back

Push back if the user asks to:

- approve a table without access patterns
- use scans or filters as primary query strategy
- add GSIs blindly for every future query
- ignore hot partition risk because adaptive capacity exists
- use TTL for exact deletion workflows
- enable global tables without conflict, replication, and failover design

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/data-modeling.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-table-design.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html
- https://docs.aws.amazon.com/prescriptive-guidance/latest/dynamodb-data-modeling/best-practices.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- DynamoDB data modeling guidance centers schema design on access patterns, partition keys, sort keys, secondary indexes, and single-table versus multi-table tradeoffs.
- Global secondary indexes support alternate partition/sort key schemas and projected attributes, but have throughput, storage, and synchronization considerations.

Sampled live evidence:
- Read-only regional availability sampling reported Amazon DynamoDB as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Sampled APIs `DynamoDB+DescribeTable` and `DynamoDB+Query` were reported `isAvailableIn` in those regions.

Review implications:
- Do not approve table design without enumerated access patterns, key cardinality/skew analysis, query-vs-scan proof, index write amplification, capacity mode, and cost/latency tradeoffs.
- Live table status, throttling, consumed capacity, and hot partitions must come from live metrics or repo/IaC evidence, not docs.

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Access patterns, item shapes, cardinality, partition-key distribution, sort-key ranges, and consistency needs
- Query/scan patterns, GSIs/LSIs, sparse indexes, projection, hot keys, adaptive capacity, and write amplification
- Capacity mode, throttling metrics, global tables, TTL, streams, backups, PITR, DAX, and cost levers
- Migration/backfill risk, index creation impact, validation queries, and rollback or dual-write plan

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS DynamoDB Data Modeling Performance Review: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```