dynamodb

name	DynamoDB
description	Design DynamoDB tables and write efficient queries avoiding common NoSQL pitfalls.
metadata	{"clawdbot":{"emoji":"⚡","requires":{"anyBins":["aws"]},"os":["linux","darwin","win32"]}}

Key Design

• Partition key determines data distribution—high-cardinality keys spread load evenly
• Hot partition = one key gets all traffic—use composite keys or add random suffix
• Sort key enables range queries within partition—design for access patterns
• Can't change keys after creation—model all access patterns before creating table

Query vs Scan

• Query uses partition key + optional sort key—O(items in partition), always prefer
• Scan reads entire table—expensive, slow, avoids indexes; almost never correct
• "I need to filter by X" usually means missing GSI—add index, don't scan
• FilterExpression applies AFTER read—still consumes full read capacity

Global Secondary Indexes

• GSI = different partition/sort key—enables alternate access patterns
• GSI is eventually consistent—writes propagate with slight delay
• GSI consumes separate capacity—provision or pay for each GSI independently
• Sparse index trick: only items with attribute appear in GSI

Single-Table Design

• One table for multiple entity types—prefix partition key: USER#123, ORDER#456
• Overloaded sort key: METADATA, ORDER#2024-01-15, ITEM#abc
• Query returns mixed types—filter client-side or use begins_with
• Not always right—start with access patterns, not doctrine

Pagination

• Results capped at 1MB per request—must handle pagination
• LastEvaluatedKey in response means more pages—pass as ExclusiveStartKey
• Loop until LastEvaluatedKey is absent—common mistake: assume one call gets all
• Limit limits evaluated items, not returned—still need pagination logic

Consistency

• Reads are eventually consistent by default—may return stale data
• ConsistentRead: true for strong consistency—costs 2x read capacity
• GSI reads always eventually consistent—no strong consistency option
• Write-then-read needs consistent read or retry—eventual consistency bites here

Conditional Writes

• ConditionExpression for optimistic locking—fails if condition false
• Prevent overwrites: attribute_not_exists(pk)
• Version check: version = :expected then increment
• ConditionCheckFailedException = retry with fresh data, don't just fail

Batch Operations

• BatchWriteItem is NOT atomic—partial success possible, check UnprocessedItems
• Retry unprocessed with exponential backoff—built into AWS SDK
• Max 25 items per batch, 16MB total—split larger batches
• No conditional writes in batch—use TransactWriteItems for atomicity

Transactions

• TransactWriteItems for atomic multi-item writes—all or nothing
• Max 100 items per transaction, 4MB total
• TransactGetItems for consistent multi-read—snapshot isolation
• 2x cost of normal operations—use only when atomicity required

TTL

• Enable TTL on timestamp attribute—DynamoDB deletes expired items automatically
• Deletion is background process—items may persist hours after expiration
• TTL value is Unix epoch seconds—milliseconds silently fails
• Filter attribute_exists(ttl) AND ttl > :now for queries if needed

Capacity

• On-demand: pay per request, auto-scales—good for unpredictable traffic
• Provisioned: set RCU/WCU, cheaper at scale—needs capacity planning
• Provisioned with auto-scaling for predictable patterns—set min/max/target
• ProvisionedThroughputExceededException = throttled—back off and retry

Limits

• Item size max 400KB—store large objects in S3, reference in DynamoDB
• Partition throughput: 3000 RCU, 1000 WCU—spread across partitions
• Query/Scan returns max 1MB—pagination required for more
• Attribute name max 64KB total per item—don't use long attribute names