Working with Items in DynamoDB
In DynamoDB, an item is a collection of attributes. Each attribute has a name and a value. An attribute value can be a scalar, a set, or a document type. For more information, see Data Types.
DynamoDB provides operations for reading and writing items. For these operations, you need to specify the items and attributes that you want to work with. When you write an item, you can specify one or more conditions that must evaluate to true. For example, you might want the write to succeed only if an item with the same key does not already exist.
This section describes how to work with items in Amazon DynamoDB. This includes reading and writing items, conditional updates, and atomic counters. This section also includes example code that uses the AWS SDKs. For best practices, see Guidelines for Working with Items.
An item consists of one or more attributes. Each attribute consists of a name, a data type, and a value. When you read or write an item, the only attributes that are required are those that make up the primary key.
For the primary key, you must provide all of its attributes. For example, with a simple primary key, you only need to specify the partition key. For a composite primary key (partition key and sort key), you must specify both the partition key and the sort key. For more information, see Primary Key.
Except for the primary key, there is no predefined schema for the items in a table. For example, to store product information, you can create a ProductCatalog table and store various product items in it such as books and bicycles. The following table shows two items, a book and a bicycle, that you can store in the ProductCatalog table. Note that the example uses JSON-like syntax to show the attribute value.
|Id (Primary Key)||Other Attributes|
An item can have any number of attributes, although there is a limit of 400 KB on the item size. An item size is the sum of lengths of its attribute names and values (binary and UTF-8 lengths); it helps if you keep the attribute names short.
Reading an Item
To read an item from a DynamoDB table, use the
You must provide the name of the table, along with the primary key of the item you want.
You need to specify the entire primary key, not just part of it. For example, if a table has a composite primary key (partition key and sort key), you must supply a value for the partition key and a value for the sort key.
The following are the default behaviors for
GetItemperforms an eventually consistent read.
GetItemreturns all of the item's attributes.
GetItemdoes not return any information about how many provisioned capacity units it consumes.
GetItem provides optional parameters so that you can override these defaults, if necessary.
DynamoDB maintains multiple copies of each item to ensure durability. For every successful write request, DynamoDB ensures that the write is durable on multiple servers. However, it takes time for a write to propagate to all copies. In DynamoDB, data is eventually consistent. This means that if you write an item and then immediately try to read it, you might not see the results from the earlier write.
By default, a
GetItem operation performs an eventually
consistent read. You can optionally request a strongly consistent read instead; this
will consume additional read capacity units, but it will return the most up-to-date
version of the item.
An eventually consistent
GetItem request consumes only half
the read capacity units as a strongly consistent request. Therefore, it is best to
design applications so that they use eventually consistent reads whenever possible.
Consistency across all copies of the data is usually reached within one
Writing an Item
To create, update, and delete items in a DynamoDB table, use the following operations:
PutItem— creates a new item. If an item with the same key already exists in the table, it is replaced with the new item. You must provide the table name and the item that you want to write.
UpdateItem— if the item does not already exist, this operation creates a new item; otherwise, it modifies an existing item's attributes. You must specify the table name and the key of the item you want to modify. For each of the attributes that you want to update, you must provide new values for them.
DeleteItem— deletes an item. You must specify the table name and the key of the item you want to delete.
For each of these operations, you need to specify the entire primary key, not just part of it. For example, if a table has a composite primary key (partition key and sort key), you must supply a value for the partition key and a value for the sort key.
If you want to avoid accidentally overwriting or deleting an existing item, you can
use a conditional expression with any of these operations. A conditional expression lets
you check whether a condition is true (such as an item already existing in the table)
before the operation can proceed. To write an item only if it doesn't already exist, use
PutItem with a conditional expression that uses the
attribute_not_exists function and the name of the table's partition key, since any item that exists will have a partition key. For more information,
see Conditional Write Operations.
In some cases, you might want DynamoDB to display certain attribute values before or
after you modify them. For example, with an
you could request that attribute values be returned as they appeared before the update
DeleteItem have a
parameter, which you can use to return the attribute values before or after they are
By default, none of these operations return any information about how many provisioned
capacity units they consume. You can use the
ReturnConsumedCapacity parameter to obtain this information.
If your application needs to read multiple items, you can use
BatchGetItem. A single
request can retrieve up to 16 MB of data, which can contain as many as
100 items. In addition, a single
BatchGetItem request can retrieve items from multiple
BatchWriteItem operation lets you put or delete multiple
BatchWriteItem can write up to 16 MB of
data, consisting of up to 25 put or delete requests. The
maximum size of an individual item is 400 KB in size. In addition, a
BatchWriteItem request can put or delete items in
multiple tables. (Note that
BatchWriteItem cannot update items. To
update items, use
A batch consists of one or more requests. For each request, DynamoDB invokes the
appropriate operation for that request. For example, if a
request contains five items, DynamoDB implicitly performs five
GetItem operations on your behalf. Similarly, if a
BatchWriteItem request contains two put requests and four
delete requests, DynamoDB implicitly performs two
PutItem and four
If an individual request in a batch should fail (for example, because you exceed the provisioned throughput settings on a table), this does not cause the entire batch to fail. Instead, the batch operation returns the keys and data from the individual failed request, so that you can retry the operation. In general, a batch operation does not fail unless all of the requests in the batch fail.
DynamoDB supports atomic counters, where you use the
UpdateItem operation to increment or decrement the value of an
existing attribute without interfering with other write requests. (All write requests
are applied in the order in which they were received.) For example, a web application
might want to maintain a counter per visitor to their site. In this case, the
application would need to increment this counter regardless of its current value.
Atomic counter updates are not idempotent. This means that the
counter will increment each time you call
UpdateItem. If you
suspect that a previous request was unsuccessful, your application could retry the
UpdateItem operation; however, this would risk updating the
counter twice. This might be acceptable for a web site counter, because you can tolerate
with slightly over- or under-counting the visitors. However, in a banking application,
it would be safer to use a conditional update rather than an atomic counter.
To update an atomic counter, use an
UpdateItem operation with an
attribute of type Number in the
UpdateExpression parameter, and
SET as the update action to perform. You can increment the counter
using a positive number, or decrement it using a negative number. For more information, see Incrementing and
Decrementing Numeric Attributes.
In a multi-user environment, multiple clients can access the same item and attempt to modify its attribute values at the same time. However, each client might not realize that other clients might have modified the item already. This is shown in the following illustration in which Client 1 and Client 2 have retrieved a copy of an item (Id=1). Client 1 changes the price from $10 to $8. Later, Client 2 changes the same item price to $12, and the previous change made by Client 1 is lost.
To help clients coordinate writes to data items, DynamoDB supports conditional
UpdateItem operations. With a conditional write, an operation
succeeds only if the item attributes meet one or more expected conditions; otherwise it
returns an error. For example, the following illustration shows both Client 1 and Client
2 retrieving a copy of an item (Id=1). Client 1 first attempts to update the item price
to $8, with the expectation that the existing item price on the server will be $10. This
operation succeeds because the expectation is met. Client 2 then attempts to update the
price to $12, with the expectation that the existing item price on the server will be
$10. This expectation cannot be met, because the price is now $8; therefore, Client 2's
Note that conditional writes are idempotent. This means that you can send the same conditional write request multiple times, but it will have no further effect on the item after the first time DynamoDB performs the specified update. For example, suppose you issue a request to update the price of a book item by 10%, with the expectation that the price is currently $20. However, before you get a response, a network error occurs and you don't know whether your request was successful or not. Because a conditional update is an idempotent operation, you can send the same request again. and DynamoDB will update the price only if the current price is still $20.
To request a conditional
UpdateItem, you specify the
condition(s) in the
ConditionExpression is a string containing attribute names,
conditional operators and built-in functions. The entire expression must evaluate to
true; otherwise the operation will fail.
For more information, see Conditional Write Operations.
If you specify the
ReturnConsumedCapacity parameter, DynamoDB will
return the number of write capacity units that were consumed during the conditional
write. (Note that write operations only consume write capacity units; they never consume
read capacity units.) Setting
TOTAL returns the write capacity consumed for the table and all
of its global secondary indexes; INDEXES returns only the write capacity consumed by
the global secondary indexes; NONE means that you do not want any consumed capacity
ConditionExpression evaluates to false during a
conditional write, DynamoDB will still consume write capacity units from the table:
If the item exists, the number of write capacity units consumed depends on the size of the item. (For example, a failed conditional write of a 1 KB item would consume one write capacity unit; if the item were twice that size, the failed conditional write would consume two write capacity units.)
If the item does not exist, DynamoDB will consume one write capacity unit.
A failed conditional write will return a
ConditionalCheckFailedException instead of the expected
response from the write operation. For this reason, you will not receive any information
about the write capacity unit that was consumed. However, you can view the
ConsumedWriteCapacityUnits metric for the table in Amazon CloudWatch
to determine the provisioned write capacity that was consumed from the table. For more
information, see DynamoDB Metrics in
Monitoring Amazon DynamoDB.
Unlike a global secondary index, a local secondary index shares its provisioned throughput capacity with its table. Read and write activity on a local secondary index consumes provisioned throughput capacity from the table.