Working with Items

In Amazon DynamoDB, an item is a collection of attributes. Each attribute has a name and a value. An attribute value can be a number, a string, a binary, or a set of any of these types. When you add an item, the primary key attribute(s) are the only required attributes. For more information, see Amazon DynamoDB Data Model . In addition to the primary key, an item can have any number of attributes, although there is a limit of 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.

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.

{                                        
   Title = "Book 101 Title"
   ISBN = "111-1111111111"
   Authors = "Author 1"
   Price = -2
   Dimensions = "8.5 x 11.0 x 0.5"
   PageCount = 500
   InPublication = 1
   ProductCategory = "Book" 
}                                    

{
   Title = "18-Bicycle 201"
   Description = "201 description"
   BicycleType = "Road"
   Brand = "Brand-Company A"
   Price = 100
   Gender = "M"
   Color = [ "Red", "Black" ]
   ProductCategory = "Bike"
}

Amazon DynamoDB provides APIs to add, retrieve, update, and delete items. In addition, it also provides an API to retrieve a batch of items from one or more tables. The PutItem, UpdateItem and DeleteItem APIs support conditional update. For example, if you use PutItem to add an item to the table, but an item with the same key already exists, Amazon DynamoDB will replace the existing item. This is the default behavior. However, you can use an Exists condition to determine whether you want the item replaced. To do this, use a conditional PutItem operation, with Exists set to false for the primary key attribute (or attributes).

In some cases, you might want Amazon DynamoDB to display certain attribute values before or after you modify them. For example, with a DeleteItem operation, you could request that the item values be retrieved before the delete happens. PutItem, UpdateItem and DeleteItem have a ReturnValues parameter, which you can use to return the attributes before or after they are modified.

Atomic Counters

Amazon DynamoDB supports atomic counters, allowing you 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.) You can use the Amazon DynamoDB UpdateItem API to increment or decrement an attribute value, rather than replacing the value. 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. Unlike the conditional update operation described in the preceding section, this is not an idempotent operation. You might retry this operation if you suspect that a previous request was unsuccessful; however, you would risk applying the same update 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.

Strongly Consistent vs. Eventually Consistent Reads

Amazon DynamoDB maintains multiple copies of each item to ensure durability. For each successful write request, Amazon DynamoDB ensures that the write is durable on multiple servers. However, it takes time for the update to propagate to all copies. The data is eventually consistent, meaning that if you write an item and then immediately try to read it, you might not see the results from the earlier write. You can optionally request a strongly consistent read; this requires additional read capacity units for Amazon DynamoDB to get the item, but it will be 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.

Capacity Units Consumed by Various Item Operations

When you create a table, you specify your read and write capacity unit requirements. When you send requests such as GetItem, UpdateItem or DeleteItem, you consume the capacity units that have been defined for the table. For more information about how Amazon DynamoDB computes the capacity units consumed by an operation, see Capacity Units Calculations for Various Operations.

You can use the Amazon DynamoDB API to work with items or use the AWS SDK libraries (http://aws.amazon.com/code). Click one of the links provided at the beginning of this section to learn more about how the specific AWS SDK library APIs support the item operations. These sections provide working code samples for Java, .NET and PHP.

In addition to .NET, Java, and PHP, the other AWS SDKs also support Amazon DynamoDB, including Android, iOS, and Ruby. For links to the complete set of AWS SDKs, see Sample Code & Libraries.