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

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.

Overview

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.

Important

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
101
{                                        
   Title = "Book 101 Title"
   ISBN = "111-1111111111"
   Authors = "Author 1"
   Price = "-2"
   Dimensions = "8.5 x 11.0 x 0.5"
   PageCount = "500"
   InPublication = true
   ProductCategory = "Book" 
}                                    
201
{
   Title = "18-Bicycle 201"
   Description = "201 description"
   BicycleType = "Road"
   Brand = "Brand-Company A"
   Price = "100"
   Color = [ "Red", "Black" ]
   ProductCategory = "Bike"
}

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 GetItem operation. 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 GetItem:

  • GetItem performs an eventually consistent read.

  • GetItem returns all of the item's attributes.

  • GetItem does 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.

Read Consistency

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 second.

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 UpdateItem operation, you could request that attribute values be returned as they appeared before the update occurs. PutItem, UpdateItem, and DeleteItem have a ReturnValues parameter, which you can use to return the attribute values before or after they are modified.

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.

Batch Operations

If your application needs to read multiple items, you can use BatchGetItem. A single BatchGetItem 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 tables.

The BatchWriteItem operation lets you put or delete multiple items. 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 singleBatchWriteItem request can put or delete items in multiple tables. (Note that BatchWriteItem cannot update items. To update items, use UpdateItem instead.)

A batch consists of one or more requests. For each request, DynamoDB invokes the appropriate operation for that request. For example, if a BatchGetItem 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 DeleteItem requests.

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.

Atomic Counters

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.

Conditional Writes

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 writes for PutItem, DeleteItem, and 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 request fails.

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 PutItem, DeleteItem, or UpdateItem, you specify the condition(s) in the ConditionExpression parameter. 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.

Tip

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 ReturnConsumedCapacity to 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 statistics returned.

If a 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.

Note

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.