PutItem - Amazon DynamoDB
DescriptionRequestsResponsesSpecial errorsExamplesRelated actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

PutItem

Important

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

For documentation on the current low-level API, see the Amazon DynamoDB API Reference.

Description

Creates a new item, or replaces an old item with a new item (including all the attributes). If an item already exists in the specified table with the same primary key, the new item completely replaces the existing item. You can perform a conditional put (insert a new item if one with the specified primary key doesn't exist), or replace an existing item if it has certain attribute values.

Attribute values may not be null; string and binary type attributes must have lengths greater than zero; and set type attributes must not be empty. Requests with empty values will be rejected with a ValidationException.

Note

To ensure that a new item does not replace an existing item, use a conditional put operation with Exists set to false for the primary key attribute, or attributes.

For more information about using PutItem, see Working with items and attributes in DynamoDB.

Requests

Syntax

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB low-level API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.PutItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Item":{
        "AttributeName1":{"S":"AttributeValue1"},
        "AttributeName2":{"N":"AttributeValue2"},
        "AttributeName5":{"B":"dmFsdWU="}
    },
    "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}},
    "ReturnValues":"ReturnValuesConstant"}
Name Description Required
TableName

The name of the table to contain the item.

Type: String

 Yes
Item

A map of the attributes for the item, and must include the primary key values that define the item. Other attribute name-value pairs can be provided for the item. For more information about primary keys, see Primary key.

Type: Map of attribute names to attribute values.

 Yes
Expected

Designates an attribute for a conditional put. The Expected parameter allows you to provide an attribute name, and whether or not DynamoDB should check to see if the attribute value already exists; or if the attribute value exists and has a particular value before changing it.

Type: Map of an attribute names to an attribute value, and whether it exists.

 No
Expected:AttributeName

The name of the attribute for the conditional put.

Type: String

 No
Expected:AttributeName: ExpectedAttributeValue Use this parameter to specify whether or not a value already exists for the attribute name-value pair.

The following JSON notation replaces the item if the "Color" attribute doesn't already exist for that item:

"Expected" :
	{"Color":{"Exists":false}}

The following JSON notation checks to see if the attribute with name "Color" has an existing value of "Yellow" before replacing the item: 

"Expected" : 
	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}

By default, if you use the Expected parameter and provide a Value, DynamoDB assumes the attribute exists and has a current value to be replaced. So you don't have to specify {"Exists":true}, because it is implied. You can shorten the request to:

"Expected" : 
	{"Color":{"Value":{"S":"Yellow"}}}
Note

If you specify {"Exists":true} without an attribute value to check, DynamoDB returns an error.

 No
ReturnValues

Use this parameter if you want to get the attribute name-value pairs before they were updated with the PutItem request. Possible parameter values are NONE (default) or ALL_OLD. If ALL_OLD is specified, and PutItem overwrote an attribute name-value pair, the content of the old item is returned. If this parameter is not provided or is NONE, nothing is returned.

Type: String

 No

Responses

Syntax

The following syntax example assumes the request specified a ReturnValues parameter of ALL_OLD; otherwise, the response has only the ConsumedCapacityUnits element.

HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 85

{"Attributes":
	{"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName2":{"SS":"AttributeValue2"},
	"AttributeName1":{"SS":"AttributeValue1"},
	},
"ConsumedCapacityUnits":1
}
Name Description
Attributes

Attribute values before the put operation, but only if the ReturnValues parameter is specified as ALL_OLD in the request.

Type: Map of attribute name-value pairs.
ConsumedCapacityUnits

The number of write capacity units consumed by the operation. This value shows the number applied toward your provisioned throughput. For more information see DynamoDB provisioned capacity mode.

Type: Number

Special errors

Error Description
ConditionalCheckFailedException Conditional check failed. An expected attribute value was not found.
ResourceNotFoundException The specified item or attribute was not found.

Examples

For examples using the Amazon SDK, see Working with items and attributes in DynamoDB.

Sample request

// This header is abbreviated. For a sample of a complete header, see DynamoDB low-level API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.PutItem 
content-type: application/x-amz-json-1.0

{"TableName":"comp5",
	"Item":
		{"time":{"N":"300"},
		"feeling":{"S":"not surprised"},
		"user":{"S":"Riley"}
		},
	"Expected":
		{"feeling":{"Value":{"S":"surprised"},"Exists":true}}
	"ReturnValues":"ALL_OLD"
}

Sample response

HTTP/1.1 200 
x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 84

{"Attributes":
	{"feeling":{"S":"surprised"},
	"time":{"N":"300"},
	"user":{"S":"Riley"}},
"ConsumedCapacityUnits":1
}