DeleteItem - Amazon DynamoDB
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).

DeleteItem

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

Deletes a single item in a table by primary key. You can perform a conditional delete operation that deletes the item if it exists, or if it has an expected attribute value.

Note

If you specify DeleteItem without attributes or values, all the attributes for the item are deleted.

Unless you specify conditions, the DeleteItem is an idempotent operation; running it multiple times on the same item or attribute does not result in an error response.

Conditional deletes are useful for only deleting items and attributes if specific conditions are met. If the conditions are met, DynamoDB performs the delete. Otherwise, the item is not deleted.

You can perform the expected conditional check on one attribute per operation.

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.DeleteItem content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Key": {"HashKeyElement":{"S":"AttributeValue1"},"RangeKeyElement":{"N":"AttributeValue2"}}, "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3"}}}, "ReturnValues":"ALL_OLD"} }
Name Description Required
TableName

The name of the table containing the item to delete.

Type: String

Yes
Key

The primary key that defines the item. For more information about primary keys, see Primary key.

Type: Map of HashKeyElement to its value and RangeKeyElement to its value.

Yes
Expected

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

Type: Map of attribute names.

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 deletes the item if the "Color" attribute doesn't 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 deleting 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 deleted. Possible parameter values are NONE (default) or ALL_OLD. If ALL_OLD is specified, 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

HTTP/1.1 200 OK x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 353 Date: Tue, 12 Jul 2011 21:31:03 GMT {"Attributes": {"AttributeName3":{"SS":["AttributeValue3","AttributeValue4","AttributeValue5"]}, "AttributeName2":{"S":"AttributeValue2"}, "AttributeName1":{"N":"AttributeValue1"} }, "ConsumedCapacityUnits":1 }
Name Description
Attributes

If the ReturnValues parameter is provided as ALL_OLD in the request, DynamoDB returns an array of attribute name-value pairs (essentially, the deleted item). Otherwise, the response contains an empty set.

Type: Array 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. Delete requests on non-existent items consume 1 write capacity unit. For more information see Managing settings on DynamoDB provisioned capacity tables.

Type: Number

Special errors

Error Description
ConditionalCheckFailedException Conditional check failed. An expected attribute value was not found.

Examples

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.DeleteItem content-type: application/x-amz-json-1.0 {"TableName":"comp-table", "Key": {"HashKeyElement":{"S":"Mingus"},"RangeKeyElement":{"N":"200"}}, "Expected": {"status":{"Value":{"S":"shopping"}}}, "ReturnValues":"ALL_OLD" }

Sample response

HTTP/1.1 200 OK x-amzn-RequestId: U9809LI6BBFJA5N2R0TB0P017JVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 353 Date: Tue, 12 Jul 2011 22:31:23 GMT {"Attributes": {"friends":{"SS":["Dooley","Ben","Daisy"]}, "status":{"S":"shopping"}, "time":{"N":"200"}, "user":{"S":"Mingus"} }, "ConsumedCapacityUnits":1 }