PutItem

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.

	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 this API, see Working with Items in Amazon DynamoDB.

Requests

Syntax

// This header is abbreviated.
// For a sample of a complete header, see Sample Amazon DynamoDB JSON Request and Response.
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"},
	},
	"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 Amazon 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, Amazon 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, Amazon 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

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 Specifying Read and Write Requirements (Provisioned Throughput). Type: Number

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 Specifying Read and Write Requirements (Provisioned Throughput).

Type: Number

Special Errors

Error	Description
`ConditionalCheckFailed`	Conditional check failed. An expected attribute value was not found.
`ResourceNotFound`	The specified item or attribute was not found.

Examples

For examples using the AWS SDK, see Working with Items in Amazon DynamoDB.

Sample Request

// This header is abbreviated. For a sample of a complete header, see Sample Amazon DynamoDB JSON Request and Response.
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
}

Description

Requests

Syntax

Responses

Syntax

Special Errors

Examples

Sample Request

Sample Response

Related Actions