4 Amazon DynamoDB in Practice

Start with access patterns

DynamoDB is a managed key-value and document database. Tables contain items, each identified by a primary key. Unlike a relational database, DynamoDB does not support arbitrary joins or queries over every attribute with equal efficiency.

Start by listing the application's access patterns. For every read, record the lookup value, any range or sort order, expected result size, and whether the result must be strongly consistent. Then map each pattern to a direct key lookup, a Query on the table, or a Query on an index.

Choose table keys

A table's composite primary key combines its partition key and sort key. The partition key locates an item collection; items with the same partition key can be queried together and ordered by sort key. A high-cardinality partition key that spreads requests across many values generally distributes traffic better than a single shared key.

For a store, three needs are to fetch an order by ID, list a customer's orders newest first with an optional date range, and find an order by tracking number. One possible key design is:

• Fetch by order ID: table key PK = ORDER#<orderId>; use GetItem.

• List a customer's orders: table key PK = CUSTOMER#<customerId> and SK = ORDER#<ISO-date>#<orderId>; use Query.

• Find by tracking number: GSI key GSI1PK = TRACKING#<trackingNumber>; use Query.

An order item could contain:

This design supports a customer's order history with one query. ISO 8601 date strings sort chronologically as strings when their format and time zone are consistent. Including the order ID in the sort key gives orders with the same timestamp distinct keys.

Choose a table organization

A single-table design stores multiple entity types together, often using key prefixes such as CUSTOMER# and ORDER#. It can make related data available through a small number of queries, but requires deliberate key conventions and may couple entity types to shared indexes.

A multi-table design keeps entity types in separate tables. It can be easier to understand and operate, especially when entities have different workloads or lifecycles. Reads that combine data may require multiple requests and application-side processing. Neither approach is automatically best; choose based on access patterns and operational needs.

Use indexes deliberately

Use a global secondary index (GSI) when a needed query starts with an attribute other than the base table's keys, such as a tracking number. A local secondary index (LSI) keeps the table's partition key but uses an alternate sort key, supporting another sort order within the same item collection. LSIs must be specified when the table is created; GSIs can be added later.

Indexes are additional data structures, not free query shortcuts. Writes to indexed items maintain their indexes, so extra indexes can increase write work and storage. Project only the attributes that queries need, and add an index only when it serves a real access pattern.

A GSI includes an item only when the item has the index key attributes. Omitting those attributes can create a sparse index for querying a subset, such as only orders requiring escalation.

Query and paginate efficiently

GetItem retrieves an item by its full primary key. Query requires equality on one partition-key value and may also constrain the sort key using a condition such as BETWEEN, begins_with, or a comparison. Put frequently used selection criteria into table or index keys when practical.

For example, a customer's orders in a time range can be queried with:

A filter expression removes items from results only after DynamoDB reads them, so it does not make a broad query efficient. A Query or Scan response is limited to 1 MB per request. If LastEvaluatedKey is present, pass it as ExclusiveStartKey in another request to continue. A page can return no items and still have a LastEvaluatedKey, for example when a filter removes every item on that page.

Use Scan cautiously: it reads every item in a table or index and then applies any filter. It can be useful for small datasets, controlled administrative tasks, or workloads that genuinely need a full traversal, but it is usually a poor substitute for a queryable access pattern.

Plan capacity and consistency

DynamoDB offers on-demand and provisioned capacity modes. On-demand capacity mode charges per request and is a practical starting point when traffic is unpredictable or changes substantially. It avoids choosing read and write capacity in advance, although sudden growth beyond the table's established traffic level can still require care.

Provisioned capacity mode sets read and write capacity for a table and its GSIs, and can suit steady, forecastable traffic. Auto scaling can adjust provisioned capacity to a configured target, but it is not an instantaneous substitute for planning around abrupt peaks.

For provisioned capacity, one read capacity unit (RCU) supports one strongly consistent read per second for an item up to 4 KB, or two eventually consistent reads per second for an item up to 4 KB. One write capacity unit (WCU) supports one write per second for an item up to 1 KB. Larger items consume capacity in increments, so estimate request rates and item sizes. Writes to GSIs also need capacity.

Manage consistency and hot keys

Reads are eventually consistent by default. A strongly consistent read is available on a table or LSI when the request supports it, but not on a GSI. Eventual consistency is often sufficient for feeds and browsing; use a strong read when a read immediately following a successful write must reflect that write.

DynamoDB hashes partition-key values to distribute data across partitions. A table can have ample total capacity and still throttle if a disproportionate share of traffic targets one key or a small set of keys. Choose keys with enough distinct values and consider how actual traffic is distributed, not just the number of records.

For example, a leaderboard with only PK = LEADERBOARD concentrates every write in one item collection. Sharding can distribute writes across keys such as LEADERBOARD#0 through LEADERBOARD#9; reads then query the shards and merge results in the application. Sharding improves write distribution but makes reads and ordering more complex. Adaptive capacity can help with uneven workloads, but does not remove the need to design for traffic hotspots.

When investigating throttling, inspect consumed and provisioned capacity, throttled requests, item size, GSI capacity, and how traffic is distributed across partition-key values. Depending on the cause, remedies may include changing the key design, sharding a hot key, adjusting provisioned capacity, or changing capacity mode.