Amazon DynamoDB is a fully managed key-value and document database. You do not pick servers, patch anything or manage partitions: you create a table, say how it is keyed, and DynamoDB spreads the data across storage partitions and replicates it across Availability Zones. The trade is that it answers a small, fixed set of questions very efficiently (give me the item with this key, give me the items under this key in this order) and answers almost nothing else cheaply. Everything on this page follows from that sentence.

Limits that shape design (checked against the DynamoDB Developer Guide, Constraints and Quotas pages, 2026-10-31; sizes use 1 KB = 1024 bytes):

Every item must have a partition key. DynamoDB feeds its value into an internal hash function, and the result decides which storage partition holds the item. That is why a read by key is fast: hash the key, go straight to one partition. It is also why items are not stored in any useful order across partitions.

A composite primary key adds a sort key. All items with the same partition key form an item collection, stored together and ordered by the sort key. That gives you Query: fetch the items of one collection, optionally narrowed by a condition on the sort key (equals, less than, between, begins_with), in ascending or descending order.

• DynamoDB allocates more partitions automatically when you raise throughput beyond what the current ones can serve, or when a partition fills up. You never manage this.
• Burst capacity: DynamoDB retains up to about five minutes of unused capacity to absorb short spikes. The docs note these details may change, so treat it as a cushion, not a plan.
• Adaptive capacity is on for every table at no extra cost. It shifts capacity toward partitions that receive more traffic, within the table total, and can isolate hot items onto their own partitions.
• Hard edges still exist: the documented per-partition maximum is 3000 read units and 1000 write units per second. A single item hammered harder than that throttles no matter how much you provision.
• Without local secondary indexes, an item collection can be split across as many partitions as needed. With an LSI, one collection is capped at 10 GB (chapter 04).

Scan reads the whole table (or index) in 1 MB pages. Cost and latency grow with table size, not with the number of matches, and the reads compete with your real traffic for capacity. A FilterExpression does not help the cost: it is applied after the items are read, before results are returned, so the read units are the same with or without it, and the 1 MB limit also applies before the filter runs. The same is true of a filter on a Query.

A Query or Scan stops at 1 MB of evaluated data or at your Limit, whichever comes first. If there is more, the response contains LastEvaluatedKey. To get the next page, send the same request with ExclusiveStartKey set to that value. When LastEvaluatedKey is absent, you have everything. Two traps:

• **A page can be empty or short and still have a LastEvaluatedKey**, especially with a filter. Loop until the key is absent; do not stop at the first empty page.
• Limit caps items evaluated per page, not items returned after a filter.
• The key is opaque state: hand it to the client as an encoded token if you build a paginated API, and treat it as untrusted input when it comes back.

The Java enhanced client's PageIterable hides this loop for you when you iterate items, and exposes each Page (with lastEvaluatedKey()) when you iterate pages. The sample in chapter 10 shows both.

The primary key gives you one access path. A secondary index gives you another one over the same items, with a different partition and/or sort key. DynamoDB maintains it for you; you only ever write to the table.

If a query asks for an attribute that is not projected, DynamoDB fetches it from the base table, at higher latency and higher read cost. Project what your query returns, not more.

• Asynchronous. Updates reach a GSI usually within a fraction of a second, but your code must tolerate a query that does not yet see a recent write, or that still shows a deleted one.
• Sparse by construction. An item appears in the GSI only if it has the index key attributes. Removing the attribute removes the item from the index. That makes a GSI an efficient "work queue" of items in a state (for example orders still pending).
• Back-pressure. The write that changes a base-table item also writes to each affected GSI, consuming the GSI's write capacity. If the GSI does not have enough, the write to the base table is throttled (the docs call this out, including while a new GSI is being created and backfilled). In provisioned mode the guidance is: give each GSI at least the table's write capacity.
• Hot GSI keys are table problems. A GSI keyed by a low-cardinality value such as ORDERSTATUS#PENDING funnels all pending-order writes into a single index key, and the throttling it causes lands on your base table.
• Each GSI costs. More indexes multiply write units and storage; add one only for a real, frequent access pattern.

Relational design starts from entities and normalisation and sorts out queries later. DynamoDB design runs the other way, and the AWS guidance is explicit: do not design the schema until you know the questions it must answer, and keep the number of tables low.

Single-table design stores several entity types (customers, orders, order lines) in one table, using generic key names (pk, sk) and prefixes in the values (CUSTOMER#..., ORDER#...). Related items share a partition key, so **one Query returns a customer and its orders, and a transaction** can span entity types with one table in one call. It is a technique, not a rule, and the trade-offs are real.

Let us apply chapter 05 to a small shop. This is the model the Java sample in chapter 10 implements and the hands-on in chapter 11 runs. First the access patterns, with frequency and the operation that serves each:

• The order header sits under the customer so A2 is one Query; the lines sit under the order so A3 is one Query. Two item collections, two queries, no join.
• **The sort key ORDER#<createdAt>#<orderId> orders by time and keeps keys unique when two orders share a millisecond. The timestamp must be fixed width** (always three fractional digits). Java's Instant.toString() drops trailing zeros, so .4Z would sort after .41Z: format it explicitly.
• **gsi1pk = ORDERSTATUS#PENDING is deliberately a hot key** to show the pattern's limit. It is fine for hundreds of writes per second at most; at real scale shard it (#0..#N) and query all shards.
• A customer with unbounded orders is acceptable here: ORDER# items carry the time, the list is paged, and no LSI caps the collection. Archive or TTL old orders if it ever matters.
• Denormalise on purpose: copy the shipping address and unit prices into the order and line items. An order is a historical fact; it must not change when the customer or catalogue does.

On-demand is described in the docs as the default and recommended option. A new on-demand table can sustain up to 4,000 writes and 12,000 reads per second, and on-demand instantly accommodates up to double the previous peak; more than double within 30 minutes can throttle, so a launch that jumps far past anything the table has seen should be pre-warmed or ramped. Default per-table quotas are 40,000 read and 40,000 write units per second and are adjustable (quotas page, 2026-10-31).

One read capacity unit reads one item up to 4 KB per second with a strongly consistent read; an eventually consistent read costs half; a transactional read costs double. One write capacity unit writes one item up to 1 KB; a transactional write costs double. Sizes round up: reads to the next 4 KB multiple, writes to the next 1 KB multiple.

Worked examples (the arithmetic follows the documented rounding rules; the item sizes are made up):

Sizing a workload (example): 200 eventually consistent reads per second of 10 KB items need 200 x 1.5 = 300 RCU. 50 writes per second of 2.5 KB items need 50 x 3 = 150 WCU; if every write also changes one GSI that projects the whole item, the GSI needs about another 150 WCU, which is the "GSI at least as large as the table" rule in numbers.

• You pay for request units or provisioned capacity, storage, and optional features (global table replication writes, backups and restores, DAX nodes, export and import). Prices vary by Region and change over time: use the pricing page and the AWS calculator, not a number from a tutorial.
• Writes are the expensive direction: roughly one unit per KB, doubled by transactions, multiplied by every GSI that is touched, multiplied again by every global table replica Region.
• Eventually consistent reads are half price: use them wherever staleness is acceptable.
• Item size is a cost lever twice: every extra KB adds write units, and every extra 4 KB adds read units. Keep hot items small and move cold bulk to S3.
• A Standard-IA table class exists for tables where storage dominates cost (old order history, logs); the Standard class is the default and is recommended for most workloads.

A successful write response means the write is durably persisted. DynamoDB gives read-committed isolation: you never see a value from a write that did not succeed, but nothing stops another writer changing the item right after your read. That gap is what conditions close.

PutItem, UpdateItem and DeleteItem accept a **ConditionExpression**. DynamoDB evaluates it against the current stored item and applies the write only if it is true, otherwise it throws ConditionalCheckFailedException. The check and the write are one atomic step on the server, so this is the primitive for: create-if-absent (attribute_not_exists(pk)), update-only-if-exists, state transitions (status = :pending), and stock checks (stock >= :qty).

Add a numeric version to the item. Read the item, change it in memory, then write with the condition version = :versionYouRead while setting version = version + 1. If somebody else wrote in between, the condition fails and you reload and retry (or give up). No locks are held, so nothing blocks, and a lost update becomes a detectable error. The Java enhanced client automates exactly this with @DynamoDbVersionAttribute (chapter 10).

UpdateItem with SET n = n + :v or ADD n :v increments inside DynamoDB, with no read first, and concurrent increments do not lose updates. It is not idempotent: if a call times out and you retry, you may count twice. Use it for approximate or tolerant counters (views, per-customer order counts). For exact accounting under retries, use a conditional write keyed by a unique event id, or a transaction. A single counter item is also a hot key at high rates.

TransactWriteItems groups up to 100 actions (Put, Update, Delete, ConditionCheck) into one all-or-nothing, idempotent operation, over distinct items in one or more tables in the same account and Region, with an aggregate size of at most 4 MB. TransactGetItems reads a set of items consistently. Facts from the transactions page:

• You cannot target the same item twice in one transaction (for example a ConditionCheck and an Update on one item).
• Transactions work on tables, not indexes.
• Each item costs two underlying writes (prepare and commit): a transactional write of an item up to 1 KB uses 2 WCU, and the capacity is consumed even if the transaction is cancelled.
• A ClientRequestToken makes the call idempotent: the token is valid for 10 minutes after the request finishes, and reusing it with different parameters returns an IdempotentParameterMismatch error. The SDKs generate a token for you.
• A conflict with another in-flight transaction on the same item fails with TransactionCanceledException; retry with backoff.
• On a multi-Region eventually consistent global table a transaction is atomic only in the Region where it ran. Replication is not transactional, so other Regions can briefly see part of it. Multi-Region strong consistency tables do not support transactions at all.

Time to Live deletes items after a timestamp you store. Enable it on the table and name an attribute holding a Number in Unix epoch seconds; items whose attribute is not a Number are ignored. Behaviour that surprises people:

• Deletion is asynchronous. Expired items are deleted by a background process, typically within a few days of expiry, not at the instant. There is no stricter guarantee in the docs.
• Expired items remain readable until deleted. Filter them out in your reads with a FilterExpression comparing the TTL attribute to now.
• The deletion consumes no write capacity in the Region where it happens. The deleted item flows to streams (marked as a service deletion rather than a user delete) and out of indexes, like any delete.
• With global tables, the TTL delete is replicated and does consume replicated write capacity in the other Regions.
• You can still update an expired item before it is deleted, including pushing the TTL forward; use a condition so you do not resurrect an item that was just deleted.

DynamoDB Streams records item-level changes in a time-ordered log kept for up to 24 hours. You choose the view when enabling it: KEYS_ONLY, NEW_IMAGE, OLD_IMAGE or NEW_AND_OLD_IMAGES. Each record appears exactly once in the stream, and changes to the same item appear in order (there is no ordering across different items). Stream reads are eventually consistent. A Lambda event source mapping polls the shards and invokes your function with batches; by default one function instance processes one shard, and ParallelizationFactor (up to 10) raises concurrency while keeping per-item order. Amazon Kinesis Data Streams is an alternative destination when you need longer retention or more consumers.

This is the natural implementation of the transactional outbox: write the business item and an event item in one TransactWriteItems (or just use the stream of the business table itself), then let a Lambda publish to your broker. See 07 Event-Driven Patterns for outbox, idempotent consumers and the dual-write problem this solves.

With MREC, a conditional write is evaluated against the item as it exists in that Region, and concurrent writes to one item in two Regions are resolved by timestamp, so one of them is silently overwritten. Design so that each item is mostly written in one Region (home-Region routing), or so a last-writer-wins merge is acceptable. Facts from the global tables pages, current version 2019.11.21, checked 2026-10-31.

The DynamoDB Enhanced Client (software.amazon.awssdk:dynamodb-enhanced) maps annotated Java beans to items. Every snippet below comes from one program that was compiled with JDK 21 against AWS SDK for Java 2.57.8 (latest release on Maven Central when this page was written) and run against DynamoDB Local; the full output is in chapter 11.

The annotations sit on the getters. @DynamoDbVersionAttribute lives in software.amazon.awssdk.enhanced.dynamodb.extensions.annotations, the others in ...enhanced.dynamodb.mapper.annotations. Several beans (Customer, Order, OrderLine) can map to the same table: build one DynamoDbTable per bean with enhanced.table("shop", TableSchema.fromBean(Order.class)), which is how single-table design looks in the enhanced client.

PAY_PER_REQUEST is on-demand. Against real AWS, drop endpointOverride and the static credentials: the default credentials provider chain and region resolution apply.

QueryConditional.sortBeginsWith builds the key condition. scanIndexForward(false) is the descending order. limit is the per-page evaluation limit. Iterating the PageIterable item by item would follow LastEvaluatedKey automatically; the sample takes the first Page explicitly to show the token.

With @DynamoDbVersionAttribute, the client's default VersionedRecordExtension writes a new item with version 1 and, on later putItem / updateItem, adds a condition that the stored version equals the one you loaded, then increments it. A stale writer gets ConditionalCheckFailedException. Passing null attributes to updateItem(item) removes them from the stored item, which is how the sample drops the order out of the sparse index.

The enhanced ConditionCheck is imported explicitly from ...enhanced.dynamodb.model, because the low-level ...services.dynamodb.model package has a class with the same name. TransactionCanceledException.cancellationReasons() returns one reason per action in request order: in the sample, an unknown customer shows ConditionalCheckFailed for the first action and None for the other two.

DynamoDB Local is a downloadable emulator of the DynamoDB API. The official image is amazon/dynamodb-local on Docker Hub; it runs java -jar DynamoDBLocal.jar -inMemory by default and listens on port 8000. The AWS documentation's own compose example uses -jar DynamoDBLocal.jar -sharedDb -dbPath ./data to persist data to a mounted folder. It accepts any access key, and region and credentials only need to be present.

Now run the chapter 10 program (the project is a plain Maven project with the dynamodb-enhanced dependency and ShopDemo as main class). It creates the table, creates a customer twice (second time rejected), places five orders through the transaction, tries one for an unknown customer, pages through orders, reads the GSI, ships one order and shows a stale writer rejected. Output below is the real output of one run, with the long lastEvaluatedKey lines shortened (abridged):

Explore with the CLI. --limit with --no-paginate shows the raw LastEvaluatedKey; without it, the CLI follows pages for you and prints a NextToken instead:

Observe: the Query touches only the customer's collection while the Scan counts the whole table (11 items in this run: 1 customer, 5 orders, 5 lines). The tiny data hides the cost difference, but ScannedCount shows it. DynamoDB Local is for functional tests: its capacity accounting, throttling, partitioning, Streams timing and global tables are not a model of the real service, so do not benchmark or capacity-plan against it. Stop it with docker stop ddb-local.

• Q: What is DynamoDB and when would you choose it?
  A managed key-value/document database with single-digit-millisecond access at any scale, no servers to manage. Choose it when access patterns are known and key-based (profiles, carts, sessions, orders by customer), when you need elastic scaling and low operations. Avoid it for ad-hoc queries, joins and analytics.
• Q: What is the difference between a partition key and a sort key?
  The partition key is hashed to pick the storage partition. The sort key orders items within one partition key value (an item collection), enabling Query with range conditions. Together they form the unique primary key.
• Q: Query vs Scan vs GetItem?
  GetItem fetches one item by full key. Query reads one item collection by partition key plus an optional sort key condition. Scan reads the whole table or index and filters afterwards, so cost follows table size. Scan belongs in exports and maintenance, not in request paths.
• Q: Does a FilterExpression reduce read cost?
  No. It is applied after items are read, so consumed capacity is the same and the 1 MB per call limit applies before filtering. Put the selective condition into the key design.
• Q: How does pagination work?
  A Query or Scan returns at most 1 MB of evaluated data (or your Limit). If there is more, LastEvaluatedKey is returned; pass it back as ExclusiveStartKey. Absent key means done. A page can be empty and still have a key when a filter is used.
• Q: How big can an item be?
  400 KB, including attribute names and values. Larger payloads go to S3 with a pointer in the item.
• Q: LSI vs GSI?
  LSI: same partition key, different sort key, created with the table, supports strongly consistent reads, shares table capacity, and caps an item collection at 10 GB. GSI: any keys, can be added later, own capacity, eventually consistent only.
• Q: Can a GSI affect the base table?
  Yes. Writes also update each affected GSI using the GSI's write capacity. If the GSI lacks capacity, the base-table write is throttled. Size GSI write capacity at least like the table and avoid hot GSI keys.
• Q: What is single-table design and its downsides?
  Several entity types in one table with generic keys and prefixes so related items share a partition key and can be fetched or transacted together. Downsides: harder to read and evolve, per-table settings (TTL, streams, PITR, capacity) cannot be tuned per entity, and a new access pattern may force re-keying. Use it where co-access justifies it.
• Q: How are read and write capacity units computed?
  Read unit = one strongly consistent read of up to 4 KB per second, eventually consistent costs half, transactional double; sizes round up to the next 4 KB. Write unit = one write of up to 1 KB, transactional double; sizes round up to the next 1 KB. A query rounds the total size once, a batch rounds per item.
• Q: On-demand or provisioned?
  On-demand for new, spiky or unpredictable workloads (pay per request, instant scaling up to double the previous peak). Provisioned with auto scaling for steady, predictable traffic where it is cheaper, optionally with reserved capacity. You can switch, with limits on how often.
• Q: What is a hot partition and how do you handle it?
  A partition receiving traffic beyond its documented 3000 read / 1000 write units per second ceiling, usually from a skewed key. Adaptive capacity helps with uneven traffic but cannot exceed the partition maximum for one item. Spread keys, shard writes, cache reads.
• Q: How do you do optimistic locking?
  A numeric version attribute: read it, then write with a condition that the version still equals what you read, incrementing it. A concurrent writer makes the condition fail, and you reload and retry. The enhanced client does this with @DynamoDbVersionAttribute.
• Q: Are atomic counters safe?
  They never lose concurrent increments, but they are not idempotent: a retried call after a timeout can count twice. Fine for tolerant counters; use conditions or transactions with unique ids for exact counts.
• Q: What are the limits of TransactWriteItems?
  Up to 100 actions over distinct items (no two actions on one item), aggregate size up to 4 MB, tables not indexes, same account and Region. It uses double capacity and is idempotent with a client token valid for 10 minutes.
• Q: When does TTL delete an item?
  Asynchronously, typically within a few days after the expiry timestamp, at no write cost. Expired items can still be read until deleted, so filter them. Deletes appear in streams and replicate through global tables.
• Q: How do Streams and Lambda support the outbox pattern?
  Streams record changes in order per item for 24 hours. A Lambda event source mapping publishes each change to a broker, so the event comes from the committed write rather than a dual write. Consumers must be idempotent because delivery to your function can repeat.
• Q: How do global tables resolve conflicts?
  In the default MREC mode, replication is asynchronous and concurrent writes to one item are resolved last-writer-wins by timestamp. MRSC mode (exactly three Regions) replicates synchronously and offers strongly consistent reads across Regions, but has no transactions, TTL or LSIs.
• Q: When would you use DAX?
  To cut latency and read load for read-heavy, eventually consistent workloads (hot items). It does not cache strongly consistent reads, is write-through, and adds a cluster and a staleness window. A local application cache is the lighter alternative.
• Q: Design question: a leaderboard top 100 per game.
  Table keyed by game and player, with a GSI keyed by game (sharded if one game is very hot) and a score sort key to read descending. A single-key "top 100" read is a Query limit 100 on that GSI. Mention eventual consistency of the GSI, write amplification and sharding the hot game key.