English for DynamoDB

DynamoDB fails in a small number of very specific, very namable ways — a hot partition, throttling, an inefficient scan — and a team that can name which one they’re hitting fixes it in minutes instead of spending an afternoon guessing at “the database is slow.”

Key Vocabulary

Partition key — the primary attribute DynamoDB uses to distribute data across underlying storage partitions; choosing one with low cardinality or uneven access patterns is the most common cause of performance problems. “We picked date as the partition key, and now every write for today’s date goes to the same partition — that’s a hot partition problem waiting to happen once traffic grows.”

Hot partition — a partition receiving disproportionately more read or write traffic than others, caused by a poorly chosen partition key, leading to throttling on that partition even when the table’s overall capacity is far from exhausted. “The table-level metrics look fine, but one customer’s ID is a hot partition — almost all their traffic lands on a single partition, which is why they’re seeing throttling that nobody else is.”

Throttling — DynamoDB rejecting a request because it exceeds the provisioned (or, in on-demand mode, momentarily available) capacity for a table or partition, returning a retryable error rather than serving the request. “Those errors aren’t a bug in our code — DynamoDB is throttling us because we burst past our provisioned write capacity during that batch import.”

Provisioned vs. on-demand capacity — two billing and scaling modes: provisioned requires specifying read/write capacity units upfront (cheaper at steady, predictable load), while on-demand scales automatically per request (simpler, but costs more per unit at scale). “We moved this table to on-demand capacity after getting paged twice for throttling during traffic spikes — provisioned was cheaper, but manually adjusting capacity ahead of every spike wasn’t sustainable.”

Scan — an operation that reads every item in a table (or a large portion of it), contrasted with a Query, which uses the partition key to read only relevant items; scans are expensive and generally a sign the access pattern wasn’t designed for DynamoDB’s model. “This endpoint is slow because it’s doing a full table scan on every request instead of a query — we need a proper access pattern with the right key structure, not just adding an index after the fact.”

Common Phrases

• “Is this throttling, or is it an actual application error?”
• “Do we have a hot partition, or is this an overall capacity problem?”
• “Should this table be on-demand instead of provisioned, given how spiky the traffic is?”
• “Is this a scan or a query — and why is it a scan?”
• “What’s the partition key here, and does it actually distribute traffic evenly?”

Example Sentences

Diagnosing throttling during an incident: “These retryable errors are throttling, not an outage — we’re bursting past our provisioned write capacity during the nightly batch job. Either we increase capacity for that window or switch this table to on-demand.”

Explaining a hot partition problem: “One tenant accounts for 40% of our traffic, and their tenant ID is our partition key — every one of their requests lands on the same partition, so they’re hitting per-partition throttling even though the table overall has plenty of headroom.”

Describing a query performance fix: “This report was doing a full table scan every time someone loaded the page — we redesigned the access pattern around a query using a composite sort key, and it went from an eight-second scan to a query that returns in milliseconds.”

Professional Tips

• Distinguish throttling from an actual outage explicitly during an incident — throttling means DynamoDB is working as designed and rejecting excess load, which needs a capacity fix, not a rollback.
• Name a hot partition directly when one tenant or key value is causing localized throttling — table-level capacity metrics won’t reveal this, and it needs a partition key redesign, not just more capacity.
• Justify the choice between provisioned and on-demand capacity with the actual traffic pattern — predictable, steady load favors provisioned; spiky or unpredictable load favors on-demand, and stating which one applies makes the tradeoff legible.
• Flag any scan in a hot code path during review — it’s rarely the right access pattern at scale, and naming it clearly (versus a query) helps a reviewer catch a design problem early.

Practice Exercise

1. Write a sentence explaining what a hot partition is and what typically causes one.
2. Explain the tradeoff between provisioned and on-demand capacity.
3. Describe why a scan is usually a sign of an access pattern that needs redesigning.