Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

Provisioned Throughput

When you create a table, you specify how much provisioned throughput capacity you want to reserve for reads and writes. DynamoDB will reserve the necessary resources to meet your throughput needs while ensuring consistent, low-latency performance. You can also change your provisioned throughput settings, increasing or decreasing capacity as needed.

In DynamoDB, you specify provisioned throughput requirements in terms of capacity units. Use the following guidelines to determine your provisioned throughput:

  • One read capacity unit represents one strongly consistent read per second, or two eventually consistent reads per second, for items up to 4 KB in size. If you need to read an item that is larger than 4 KB, DynamoDB will need to consume additional read capacity units. The total number of read capacity units required depends on the item size, and whether you want an eventually consistent or strongly consistent read.

  • One write capacity unit represents one write per second for items up to 1 KB in size. If you need to write an item that is larger than 1 KB, DynamoDB will need to consume additional write capacity units. The total number of write capacity units required depends on the item size.

For tables with secondary indexes, DynamoDB will consume additional capacity units. For example, if you wanted to add a single 1 KB item to a table, and that item contained an indexed attribute, you would need two write capacity units—one for writing to the table and another for writing to the index. For more information, see:

If your application's read or write requests exceed the provisioned throughput for a table, DynamoDB might throttle that request. When this happens, the request fails with an HTTP 400 code (Bad Request), accompanied by a ProvisionedThroughputExceededException. The AWS SDKs have built-in support for retrying throttled requests. However, you might want to consider using exponential backoff logic in your error handling code. For more information, see Error Retries and Exponential Backoff.

You can use the AWS Management Console to monitor your provisioned and actual throughput, to determine whether any requests are being throttled and change your provisioned capacity settings in anticipation of traffic changes.

Read Capacity Units

If your items are smaller than 4 KB in size, each read capacity unit will yield one strongly consistent read per second or two eventually consistent reads per second.

For example, suppose that you want to read 80 items per second from a table. Suppose that the items are 3 KB in size and you want strongly consistent reads. For this scenario, each read would require one provisioned read capacity unit. To determine this, you divide the item size of the operation by 4 KB, and then round up to the nearest whole number, as shown following:

3 KB / 4 KB = 0.75 --> 1

For this scenario, you need to set the table's provisioned read throughput to 80 read capacity units:

1 read capacity unit per item × 80 reads per second = 80 read capacity units

If you wanted eventually consistent reads instead of strongly consistent reads, you would only need to provision 40 read capacity units.

If your items are larger than 4 KB, you need to round the item size up to the next 4 KB boundary. For example, suppose that you want to perform 100 strongly consistent reads per second, and that the items are 6 KB in size. First, you need to determine the number of read capacity units required per item and round it up to the nearest whole number, as shown following:

6 KB / 4 KB = 1.5 --> 2

The result is two read capacity units per item. Now, you multiply this by the number of strongly consistent reads per second:

2 read capacity units per item × 100 reads per second = 200

Thus, you would need to set the table's provisioned read capacity units to 200. (If you wanted eventually consistent reads instead of strongly consistent reads, then you would only need to provision 100 read capacity units.)

To read a single item, you use the GetItem operation. If you want to read multiple items, you can use BatchGetItem to retrieve up to 100 items from a table.

You can use the Query and Scan operations to retrieve multiple consecutive items from a table or an index, in a single request. With these operations, DynamoDB uses the cumulative size of the processed items to calculate provisioned throughput. For example, if a Query operation retrieves 100 items that are 1 KB each, the read capacity calculation is not (100 × 4 KB) = 100 read capacity units, as if those items had been retrieved individually using GetItem or BatchGetItem. Instead, the total would be only 25 read capacity units, as shown following:

(100 * 1024 bytes = 100 KB) / 4 KB = 25 read capacity units

For more information see Item Size Calculations.

Write Capacity Units

If your items are smaller than 1 KB in size, each write capacity unit will yield one write per second. For example, suppose that you want to write 100 items per second to your table, and that the items are 512 bytes in size. For this scenario, each write would require one provisioned write capacity unit. To determine this, you divide the item size of the operation by 1 KB, and then round up to the nearest whole number:

512 bytes / 1 KB = 0.5 --> 1

For this scenario, you would want to set the table's provisioned read throughput to 100 write capacity units:

1 write capacity unit per item × 100 writes per second = 100 write capacity units

If your items are larger than 1 KB in size, you need to round the item size up to the next 1 KB boundary. For example, suppose that you wanted to perform 10 writes per second, and that the items are 1.5 KB in size. First, you would determine the number of write capacity units required per item, rounding up to the nearest whole number, as shown following:

1.5 KB / 1 KB = 1.5 --> 2

The result is two write capacity units per item. Now, you multiply this by the number of writes per second:

2 write capacity units per item × 10 writes per second = 20 write capacity units

Thus, you need to set the table's provisioned write capacity units to 20 in this scenario.

To work with a single item, use the PutItem, UpdateItem, or DeleteItem operation as appropriate. You can also use BatchWriteItem to put or delete up to 25 items in a single operation. Note that BatchWriteItem does not support item updates.

Purchasing Reserved Capacity

DynamoDB allows customers to purchase reserved capacity, as described at Amazon DynamoDB Pricing. With reserved capacity, you pay a one-time upfront fee and commit to a minimum usage level over a period of time. By reserving your read and write capacity units ahead of time, you realize significant cost savings compared to on-demand provisioned throughput settings.

To manage reserved capacity, go to the DynamoDB console and choose Reserved Capacity.

Note

You can prevent users from viewing or purchasing reserved capacity, while still allowing them to access the rest of the console. For more information, see "Grant Permissions to Prevent Purchasing of Reserved Capacity Offerings" in Authentication and Access Control for Amazon DynamoDB.