Amazon DynamoDB
API Reference (API Version 2012-08-10)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

DeleteItem

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.

In addition to deleting an item, you can also return the item's attribute values in the same operation, using the ReturnValues parameter.

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 if specific conditions are met. If those conditions are met, DynamoDB performs the delete. Otherwise, the item is not deleted.

Request Syntax

{
    "ConditionalOperator": "string",
    "Expected": 
        {
            "string" :
                {
                    "AttributeValueList": [
                        {
                            "B": "blob",
                            "BS": [
                                "blob"
                            ],
                            "N": "string",
                            "NS": [
                                "string"
                            ],
                            "S": "string",
                            "SS": [
                                "string"
                            ]
                        }
                    ],
                    "ComparisonOperator": "string",
                    "Exists": "boolean",
                    "Value": {
                        "B": "blob",
                        "BS": [
                            "blob"
                        ],
                        "N": "string",
                        "NS": [
                            "string"
                        ],
                        "S": "string",
                        "SS": [
                            "string"
                        ]
                    }
                }
        },
    "Key": 
        {
            "string" :
                {
                    "B": "blob",
                    "BS": [
                        "blob"
                    ],
                    "N": "string",
                    "NS": [
                        "string"
                    ],
                    "S": "string",
                    "SS": [
                        "string"
                    ]
                }
        },
    "ReturnConsumedCapacity": "string",
    "ReturnItemCollectionMetrics": "string",
    "ReturnValues": "string",
    "TableName": "string"
}
			

Request Parameters

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

Key

A map of attribute names to AttributeValue objects, representing the primary key of the item to delete.

For the primary key, you must provide all of the attributes. For example, with a hash type primary key, you only need to specify the hash attribute. For a hash-and-range type primary key, you must specify both the hash attribute and the range attribute.

Type: String to AttributeValue object map

Required: Yes

TableName

The name of the table from which to delete the item.

Type: String

Length constraints: Minimum length of 3. Maximum length of 255.

Required: Yes

ConditionalOperator

A logical operator to apply to the conditions in the Expected map:

  • AND - If all of the conditions evaluate to true, then the entire map evaluates to true.

  • OR - If at least one of the conditions evaluate to true, then the entire map evaluates to true.

If you omit ConditionalOperator, then AND is the default.

The operation will succeed only if the entire map evaluates to true.

Type: String

Valid Values: AND | OR

Required: No

Expected

A map of attribute/condition pairs. This is the conditional block for the DeleteItem operation.

Each element of Expected consists of an attribute name, a comparison operator, and one or more values. DynamoDB compares the attribute with the value(s) you supplied, using the comparison operator. For each Expected element, the result of the evaluation is either true or false.

If you specify more than one element in the Expected map, then by default all of the conditions must evaluate to true. In other words, the conditions are ANDed together. (You can use the ConditionalOperator parameter to OR the conditions instead. If you do this, then at least one of the conditions must evaluate to true, rather than all of them.)

If the Expected map evaluates to true, then the conditional operation succeeds; otherwise, it fails.

Each item in Expected represents an attribute name for DynamoDB to check, along with an AttributeValueList and a ComparisonOperator:

  • AttributeValueList - One or more values to evaluate against the supplied attribute. The number of values in the list depends on the ComparisonOperator being used.

    For type Number, value comparisons are numeric.

    String value comparisons for greater than, equals, or less than are based on ASCII character code values. For example, a is greater than A, and aa is greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.

    For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions.

  • ComparisonOperator - A comparator for evaluating attributes in the AttributeValueList. When performing the comparison, DynamoDB uses strongly consistent reads.

    The following comparison operators are available:

    EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN

    The following are descriptions of each comparison operator.

    • EQ : Equal.

      AttributeValueList can contain only one AttributeValue of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not equal {"NS":["6", "2", "1"]}.

    • NE : Not equal.

      AttributeValueList can contain only one AttributeValue of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not equal {"NS":["6", "2", "1"]}.

    • LE : Less than or equal.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not compare to {"NS":["6", "2", "1"]}.

    • LT : Less than.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not compare to {"NS":["6", "2", "1"]}.

    • GE : Greater than or equal.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not compare to {"NS":["6", "2", "1"]}.

    • GT : Greater than.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not equal {"N":"6"}. Also, {"N":"6"} does not compare to {"NS":["6", "2", "1"]}.

    • NOT_NULL : The attribute exists.

    • NULL : The attribute does not exist.

    • CONTAINS : checks for a subsequence, or value in a set.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operator checks for a substring match. If the target attribute of the comparison is Binary, then the operator looks for a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("SS", "NS", or "BS"), then the operator evaluates to true if it finds an exact match with any member of the set.

    • NOT_CONTAINS : checks for absence of a subsequence, or absence of a value in a set.

      AttributeValueList can contain only one AttributeValue of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operator checks for the absence of a substring match. If the target attribute of the comparison is Binary, then the operator checks for the absence of a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("SS", "NS", or "BS"), then the operator evaluates to true if it does not find an exact match with any member of the set.

    • BEGINS_WITH : checks for a prefix.

      AttributeValueList can contain only one AttributeValue of type String or Binary (not a Number or a set). The target attribute of the comparison must be a String or Binary (not a Number or a set).

    • IN : checks for matching elements within two sets.

      AttributeValueList can contain one or more AttributeValue elements of type String, Number, or Binary (not a set). These attributes are compared against an existing Set type attribute of an item.

      If the existing attribute is equal to any of the attributes provided in AttributeValueList, then the expression evaluates to true.

      If the existing attribute is a set, it cannot be equal to any of the input items because the data types are different; thus, the expression evaluates to false.

    • BETWEEN : Greater than or equal to the first value, and less than or equal to the second value.

      AttributeValueList must contain two AttributeValue elements of the same type, either String, Number, or Binary (not a set). A target attribute matches if the target value is greater than, or equal to, the first element and less than, or equal to, the second element. If an item contains an AttributeValue of a different type than the one specified in the request, the value does not match. For example, {"S":"6"} does not compare to {"N":"6"}. Also, {"N":"6"} does not compare to {"NS":["6", "2", "1"]}

For usage examples of AttributeValueList and ComparisonOperator, see Conditional Expressions in the Amazon DynamoDB Developer Guide.

Note

For backward compatibility with previous DynamoDB releases, the following parameters can be used instead of AttributeValueList and ComparisonOperator:

  • Value - A value for DynamoDB to compare with an attribute.

  • Exists - Causes DynamoDB to evaluate the value before attempting the conditional operation:

    • If Exists is true, DynamoDB will check to see if that attribute value already exists in the table. If it is found, then the condition evaluates to true; otherwise the condition evaluate to false.

    • If Exists is false, DynamoDB assumes that the attribute value does not exist in the table. If in fact the value does not exist, then the assumption is valid and the condition evaluates to true. If the value is found, despite the assumption that it does not exist, the condition evaluates to false.

Even though DynamoDB continues to accept the Value and Exists parameters, they are now deprecated. We recommend that you use AttributeValueList and ComparisonOperator instead, since they allow you to construct a much wider range of conditions.

The Value and Exists parameters are incompatible with AttributeValueList and ComparisonOperator. If you attempt to use both sets of parameters at once, DynamoDB will throw a ValidationException.

Type: String to ExpectedAttributeValue object map

Required: No

ReturnConsumedCapacity

If set to TOTAL, the response includes ConsumedCapacity data for tables and indexes. If set to INDEXES, the response includes ConsumedCapacity for indexes. If set to NONE (the default), ConsumedCapacity is not included in the response.

Type: String

Valid Values: INDEXES | TOTAL | NONE

Required: No

ReturnItemCollectionMetrics

If set to SIZE, statistics about item collections, if any, that were modified during the operation are returned in the response. If set to NONE (the default), no statistics are returned.

Type: String

Valid Values: SIZE | NONE

Required: No

ReturnValues

Use ReturnValues if you want to get the item attributes as they appeared before they were deleted. For DeleteItem, the valid values are:

  • NONE - If ReturnValues is not specified, or if its value is NONE, then nothing is returned. (This is the default for ReturnValues.)

  • ALL_OLD - The content of the old item is returned.

Type: String

Valid Values: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW

Required: No

Response Syntax

{
    "Attributes": 
        {
            "string" :
                {
                    "B": "blob",
                    "BS": [
                        "blob"
                    ],
                    "N": "string",
                    "NS": [
                        "string"
                    ],
                    "S": "string",
                    "SS": [
                        "string"
                    ]
                }
        },
    "ConsumedCapacity": {
        "CapacityUnits": "number",
        "GlobalSecondaryIndexes": 
            {
                "string" :
                    {
                        "CapacityUnits": "number"
                    }
            },
        "LocalSecondaryIndexes": 
            {
                "string" :
                    {
                        "CapacityUnits": "number"
                    }
            },
        "Table": {
            "CapacityUnits": "number"
        },
        "TableName": "string"
    },
    "ItemCollectionMetrics": {
        "ItemCollectionKey": 
            {
                "string" :
                    {
                        "B": "blob",
                        "BS": [
                            "blob"
                        ],
                        "N": "string",
                        "NS": [
                            "string"
                        ],
                        "S": "string",
                        "SS": [
                            "string"
                        ]
                    }
            },
        "SizeEstimateRangeGB": [
            "number"
        ]
    }
}
			

Response Elements

The following data is returned in JSON format by the service.

Attributes

A map of attribute names to AttributeValue objects, representing the item as it appeared before the DeleteItem operation. This map appears in the response only if ReturnValues was specified as ALL_OLD in the request.

Type: String to AttributeValue object map

ConsumedCapacity

Represents the capacity units consumed by an operation. The data returned includes the total provisioned throughput consumed, along with statistics for the table and any indexes involved in the operation. ConsumedCapacity is only returned if it was asked for in the request. For more information, see Provisioned Throughput in the Amazon DynamoDB Developer Guide.

Type: ConsumedCapacity object

ItemCollectionMetrics

Information about item collections, if any, that were affected by the operation. ItemCollectionMetrics is only returned if it was asked for in the request. If the table does not have any local secondary indexes, this information is not returned in the response.

Each ItemCollectionMetrics element consists of:

  • ItemCollectionKey - The hash key value of the item collection. This is the same as the hash key of the item.

  • SizeEstimateRange - An estimate of item collection size, measured in gigabytes. This is a two-element array containing a lower bound and an upper bound for the estimate. The estimate includes the size of all the items in the table, plus the size of all attributes projected into all of the local secondary indexes on that table. Use this estimate to measure whether a local secondary index is approaching its size limit.

    The estimate is subject to change over time; therefore, do not rely on the precision or accuracy of the estimate.

Type: ItemCollectionMetrics object

Errors

For information about the errors that are common to all actions, see Common Errors.

ConditionalCheckFailedException

A condition specified in the operation could not be evaluated.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

ItemCollectionSizeLimitExceededException

An item collection is too large. This exception is only returned for tables that have one or more local secondary indexes.

HTTP Status Code: 400

ProvisionedThroughputExceededException

The request rate is too high, or the request is too large, for the available throughput to accommodate. The AWS SDKs automatically retry requests that receive this exception; therefore, your request will eventually succeed, unless the request is too large or your retry queue is too large to finish. Reduce the frequency of requests by using the strategies listed in Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide.

HTTP Status Code: 400

ResourceNotFoundException

The operation tried to access a nonexistent table or index. The resource may not be specified correctly, or its status may not be ACTIVE.

HTTP Status Code: 400

Examples

Delete an Item

This example deletes an item from the Thread table, but only if that item does not have an attribute named Replies. Because ReturnValues is set to ALL_OLD, the response contains the item as it appeared before the delete.

Sample Request

POST / HTTP/1.1
Host: dynamodb.<region>.<domain>;
X-Amz-Date: <Date>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-length;content-type;host;user-agent;x-amz-content-sha256;x-amz-date;x-amz-target, Signature=<Signature>
User-Agent: <UserAgentString>
x-amz-content-sha256: <PayloadHash>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>     
Connection: Keep-Alive X-Amz-Target: DynamoDB_20120810.DeleteItem 

{
    "TableName": "Thread",
    "Key": {
        "ForumName": {
            "S": "Amazon DynamoDB"
        },
        "Subject": {
            "S": "How do I update multiple items?"
        }
    },
    "Expected": {
        "Replies": {
            "ComparisonOperator": "NULL"
        }
    },
    "ReturnValues": "ALL_OLD"
}
        

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId> 
x-amz-crc32: <Checksum>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
Date: <Date>
 {
    "Attributes": {
        "LastPostedBy": {
            "S": "fred@example.com"
        },
        "ForumName": {
            "S": "Amazon DynamoDB"
        },
        "LastPostDateTime": {
            "S": "201303201023"
        },
        "Tags": {
            "SS": ["Update","Multiple Items","HelpMe"]
        },
        "Subject": {
            "S": "How do I update multiple items?"
        },
        "Message": {
            "S": "I want to update multiple items in a single API call. What's the best way to do that?"
        }
    }
}