aws-dynamodb

---

Description: AWS DynamoDB Best Practices Globs: /dynamodb//.ts, /models//.ts, /database//.ts, /repositories//.ts

AWS DynamoDB Development Standards

@base.mdc @typescript.mdc

Data Modeling Principles

• Design for query patterns, not data relationships
• Start with access patterns before determining table structure
• Use single-table design for related entities when appropriate
• Keep item sizes small (preferably under 4KB)
• Avoid overly normalized data structures
• Balance between read and write efficiency based on workload
• Design with future growth and changing access patterns in mind

Key Design

• Choose partition keys with high cardinality to distribute data evenly
• Avoid partition keys that could create hot spots
• Use composite sort keys for hierarchical relationships
• Design sort keys to support range queries efficiently
• Use meaningful prefixes in sort keys for item collection filtering
• Implement composite keys with delimiters (e.g., USER#123#PROFILE)
• Consider using GSIs for alternative access patterns

Item Structure

• Use consistent attribute naming conventions
• Include entity type discriminator attributes
• Denormalize data when it supports common access patterns
• Use short attribute names for frequently accessed items
• Store date/time values in ISO format
• Use consistent JSON serialization for complex nested objects
• Consider compression for large attribute values

Secondary Indexes

• Use sparse indexes where appropriate
• Create GSIs only for required access patterns
• Keep index projections minimal (KEYS_ONLY or INCLUDE specific attributes)
• Use LSIs sparingly due to partition size limits
• Design indexes to support efficient query patterns
• Consider overloading indexes for multiple access patterns
• Use index sort keys to enable range filtering

Query Optimization

• Use query operations instead of scans whenever possible
• Implement pagination for large result sets
• Use consistent reads for time-sensitive operations
• Use eventually consistent reads for non-critical operations
• Batch operations for multiple items when possible
• Leverage query filtering only for post-filtering, not as a primary filter
• Implement cursor-based pagination over offset-based