Table Of Contents

Feedback

User Guide

First time using the AWS CLI? See the User Guide for help getting started.

[ aws . dynamodb ]

delete-item

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.

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

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.

Synopsis

  delete-item
--table-name <value>
--key <value>
[--expected <value>]
[--conditional-operator <value>]
[--return-values <value>]
[--return-consumed-capacity <value>]
[--return-item-collection-metrics <value>]
[--condition-expression <value>]
[--expression-attribute-names <value>]
[--expression-attribute-values <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

Options

--table-name (string)

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

--key (map)

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 simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key.

JSON Syntax:

{"string": {
      "S": "string",
      "N": "string",
      "B": blob,
      "SS": ["string", ...],
      "NS": ["string", ...],
      "BS": [blob, ...],
      "M": {"string": {
            "S": "string",
            "N": "string",
            "B": blob,
            "SS": ["string", ...],
            "NS": ["string", ...],
            "BS": [blob, ...],
            "M": {"string": { ... recursive ... }
              ...},
            "L": [
              { ... recursive ... }
              ...
            ],
            "NULL": true|false,
            "BOOL": true|false
          }
        ...},
      "L": [
        {
          "S": "string",
          "N": "string",
          "B": blob,
          "SS": ["string", ...],
          "NS": ["string", ...],
          "BS": [blob, ...],
          "M": {"string": { ... recursive ... }
            ...},
          "L": [
            { ... recursive ... }
            ...
          ],
          "NULL": true|false,
          "BOOL": true|false
        }
        ...
      ],
      "NULL": true|false,
      "BOOL": true|false
    }
  ...}

--expected (map)

This is a legacy parameter. Use condition-expression instead. For more information, see Expected in the Amazon DynamoDB Developer Guide .

JSON Syntax:

{"string": {
      "Value": {
        "S": "string",
        "N": "string",
        "B": blob,
        "SS": ["string", ...],
        "NS": ["string", ...],
        "BS": [blob, ...],
        "M": {"string": {
              "S": "string",
              "N": "string",
              "B": blob,
              "SS": ["string", ...],
              "NS": ["string", ...],
              "BS": [blob, ...],
              "M": {"string": { ... recursive ... }
                ...},
              "L": [
                { ... recursive ... }
                ...
              ],
              "NULL": true|false,
              "BOOL": true|false
            }
          ...},
        "L": [
          {
            "S": "string",
            "N": "string",
            "B": blob,
            "SS": ["string", ...],
            "NS": ["string", ...],
            "BS": [blob, ...],
            "M": {"string": { ... recursive ... }
              ...},
            "L": [
              { ... recursive ... }
              ...
            ],
            "NULL": true|false,
            "BOOL": true|false
          }
          ...
        ],
        "NULL": true|false,
        "BOOL": true|false
      },
      "Exists": true|false,
      "ComparisonOperator": "EQ"|"NE"|"IN"|"LE"|"LT"|"GE"|"GT"|"BETWEEN"|"NOT_NULL"|"NULL"|"CONTAINS"|"NOT_CONTAINS"|"BEGINS_WITH",
      "AttributeValueList": [
        {
          "S": "string",
          "N": "string",
          "B": blob,
          "SS": ["string", ...],
          "NS": ["string", ...],
          "BS": [blob, ...],
          "M": {"string": {
                "S": "string",
                "N": "string",
                "B": blob,
                "SS": ["string", ...],
                "NS": ["string", ...],
                "BS": [blob, ...],
                "M": {"string": { ... recursive ... }
                  ...},
                "L": [
                  { ... recursive ... }
                  ...
                ],
                "NULL": true|false,
                "BOOL": true|false
              }
            ...},
          "L": [
            {
              "S": "string",
              "N": "string",
              "B": blob,
              "SS": ["string", ...],
              "NS": ["string", ...],
              "BS": [blob, ...],
              "M": {"string": { ... recursive ... }
                ...},
              "L": [
                { ... recursive ... }
                ...
              ],
              "NULL": true|false,
              "BOOL": true|false
            }
            ...
          ],
          "NULL": true|false,
          "BOOL": true|false
        }
        ...
      ]
    }
  ...}

--conditional-operator (string)

This is a legacy parameter. Use condition-expression instead. For more information, see conditional-operator in the Amazon DynamoDB Developer Guide .

Possible values:

  • AND
  • OR

--return-values (string)

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

  • NONE - If ReturnValues is not specified, or if its value is NONE , then nothing is returned. (This setting is the default for ReturnValues .)
  • ALL_OLD - The content of the old item is returned.

Note

The ReturnValues parameter is used by several DynamoDB operations; however, delete-item does not recognize any values other than NONE or ALL_OLD .

Possible values:

  • NONE
  • ALL_OLD
  • UPDATED_OLD
  • ALL_NEW
  • UPDATED_NEW

--return-consumed-capacity (string)

Determines the level of detail about provisioned throughput consumption that is returned in the response:

  • INDEXES - The response includes the aggregate ConsumedCapacity for the operation, together with ConsumedCapacity for each table and secondary index that was accessed. Note that some operations, such as get-item and batch-get-item , do not access any indexes at all. In these cases, specifying INDEXES will only return ConsumedCapacity information for table(s).
  • TOTAL - The response includes only the aggregate ConsumedCapacity for the operation.
  • NONE - No ConsumedCapacity details are included in the response.

Possible values:

  • INDEXES
  • TOTAL
  • NONE

--return-item-collection-metrics (string)

Determines whether item collection metrics are returned. If set to SIZE , the response includes 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.

Possible values:

  • SIZE
  • NONE

--condition-expression (string)

A condition that must be satisfied in order for a conditional delete-item to succeed.

An expression can contain any of the following:

  • Functions: attribute_exists | attribute_not_exists | attribute_type | contains | begins_with | size These function names are case-sensitive.
  • Comparison operators: = | | | | = | = | BETWEEN | IN
  • Logical operators: AND | OR | NOT

For more information on condition expressions, see Specifying Conditions in the Amazon DynamoDB Developer Guide .

--expression-attribute-names (map)

One or more substitution tokens for attribute names in an expression. The following are some use cases for using ExpressionAttributeNames :

  • To access an attribute whose name conflicts with a DynamoDB reserved word.
  • To create a placeholder for repeating occurrences of an attribute name in an expression.
  • To prevent special characters in an attribute name from being misinterpreted in an expression.

Use the # character in an expression to dereference an attribute name. For example, consider the following attribute name:

  • Percentile

The name of this attribute conflicts with a reserved word, so it cannot be used directly in an expression. (For the complete list of reserved words, see Reserved Words in the Amazon DynamoDB Developer Guide ). To work around this, you could specify the following for ExpressionAttributeNames :

  • {"#P":"Percentile"}

You could then use this substitution in an expression, as in this example:

  • #P = :val

Note

Tokens that begin with the : character are expression attribute values , which are placeholders for the actual value at runtime.

For more information on expression attribute names, see Accessing Item Attributes in the Amazon DynamoDB Developer Guide .

Shorthand Syntax:

KeyName1=string,KeyName2=string

JSON Syntax:

{"string": "string"
  ...}

--expression-attribute-values (map)

One or more values that can be substituted in an expression.

Use the : (colon) character in an expression to dereference an attribute value. For example, suppose that you wanted to check whether the value of the ProductStatus attribute was one of the following:

Available | Backordered | Discontinued

You would first need to specify ExpressionAttributeValues as follows:

{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, ":disc":{"S":"Discontinued"} }

You could then use these values in an expression, such as this:

ProductStatus IN (:avail, :back, :disc)

For more information on expression attribute values, see Specifying Conditions in the Amazon DynamoDB Developer Guide .

JSON Syntax:

{"string": {
      "S": "string",
      "N": "string",
      "B": blob,
      "SS": ["string", ...],
      "NS": ["string", ...],
      "BS": [blob, ...],
      "M": {"string": {
            "S": "string",
            "N": "string",
            "B": blob,
            "SS": ["string", ...],
            "NS": ["string", ...],
            "BS": [blob, ...],
            "M": {"string": { ... recursive ... }
              ...},
            "L": [
              { ... recursive ... }
              ...
            ],
            "NULL": true|false,
            "BOOL": true|false
          }
        ...},
      "L": [
        {
          "S": "string",
          "N": "string",
          "B": blob,
          "SS": ["string", ...],
          "NS": ["string", ...],
          "BS": [blob, ...],
          "M": {"string": { ... recursive ... }
            ...},
          "L": [
            { ... recursive ... }
            ...
          ],
          "NULL": true|false,
          "BOOL": true|false
        }
        ...
      ],
      "NULL": true|false,
      "BOOL": true|false
    }
  ...}

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.

Examples

To delete an item

This example deletes an item from the MusicCollection table.

Command:

aws dynamodb delete-item --table-name MusicCollection --key file://key.json

The arguments for --key are stored in a JSON file, key.json. Here are the contents of that file:

{
    "Artist": {"S": "No One You Know"},
    "SongTitle": {"S": "Scared of My Shadow"}
}

Output:

{
    "ConsumedCapacity": {
        "CapacityUnits": 1.0,
        "TableName": "MusicCollection"
    }
}

Output

Attributes -> (map)

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

key -> (string)

value -> (structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

value -> (structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

( ... recursive ... )

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

( ... recursive ... )

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

(structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

( ... recursive ... )

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

( ... recursive ... )

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

ConsumedCapacity -> (structure)

The capacity units consumed by the delete-item 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 the return-consumed-capacity parameter was specified. For more information, see Provisioned Throughput in the Amazon DynamoDB Developer Guide .

TableName -> (string)

The name of the table that was affected by the operation.

CapacityUnits -> (double)

The total number of capacity units consumed by the operation.

Table -> (structure)

The amount of throughput consumed on the table affected by the operation.

CapacityUnits -> (double)

The total number of capacity units consumed on a table or an index.

LocalSecondaryIndexes -> (map)

The amount of throughput consumed on each local index affected by the operation.

key -> (string)

value -> (structure)

Represents the amount of provisioned throughput capacity consumed on a table or an index.

CapacityUnits -> (double)

The total number of capacity units consumed on a table or an index.

GlobalSecondaryIndexes -> (map)

The amount of throughput consumed on each global index affected by the operation.

key -> (string)

value -> (structure)

Represents the amount of provisioned throughput capacity consumed on a table or an index.

CapacityUnits -> (double)

The total number of capacity units consumed on a table or an index.

ItemCollectionMetrics -> (structure)

Information about item collections, if any, that were affected by the delete-item operation. ItemCollectionMetrics is only returned if the return-item-collection-metrics parameter was specified. 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 partition key value of the item collection. This is the same as the partition key value of the item itself.
  • SizeEstimateRangeGB - An estimate of item collection size, in gigabytes. This value 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.

ItemCollectionKey -> (map)

The partition key value of the item collection. This value is the same as the partition key value of the item.

key -> (string)

value -> (structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

value -> (structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

( ... recursive ... )

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

( ... recursive ... )

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

(structure)

Represents the data for an attribute.

Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

For more information, see Data Types in the Amazon DynamoDB Developer Guide .

S -> (string)

An attribute of type String. For example:

"S": "Hello"

N -> (string)

An attribute of type Number. For example:

"N": "123.45"

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

B -> (blob)

An attribute of type Binary. For example:

"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

SS -> (list)

An attribute of type String Set. For example:

"SS": ["Giraffe", "Hippo" ,"Zebra"]

(string)

NS -> (list)

An attribute of type Number Set. For example:

"NS": ["42.2", "-19", "7.5", "3.14"]

Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

(string)

BS -> (list)

An attribute of type Binary Set. For example:

"BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

(blob)

M -> (map)

An attribute of type Map. For example:

"M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

key -> (string)

( ... recursive ... )

L -> (list)

An attribute of type List. For example:

"L": ["Cookies", "Coffee", 3.14159]

( ... recursive ... )

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

NULL -> (boolean)

An attribute of type Null. For example:

"NULL": true

BOOL -> (boolean)

An attribute of type Boolean. For example:

"BOOL": true

SizeEstimateRangeGB -> (list)

An estimate of item collection size, in gigabytes. This value 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.

(double)