aws dynamodb update-item

Edits an existing item's attributes, or adds a new item to the table if it does not already exist. AWS CLI reference

2 examples 11 options Its page in the AWS CLI reference

Examples

from aws-cli, each command read by CmdID

Example 1: To update an item in a table

The following update-item example updates an item in the MusicCollection table. It adds a new attribute (Year) and modifies the AlbumTitle attribute. All of the attributes in the item, as they appear after the update, are returned in the response.

aws dynamodb update-item --table-name MusicCollection --key file://key.json --update-expression "SET #Y = :y, #AT = :t" --expression-attribute-names file://expression-attribute-names.json --expression-attribute-values file://expression-attribute-values.json --return-values ALL_NEW --return-consumed-capacity TOTAL --return-item-collection-metrics SIZE

Identify

--table-nameThe name of the table containing the item to update.

--keyThe primary key of the item to be updated.

--update-expressionAn expression that defines one or more attributes to be updated, the action to be performed on them, and new values for them.

--expression-attribute-namesOne or more substitution tokens for attribute names in an expression.

--expression-attribute-valuesOne or more values that can be substituted in an expression.

--return-valuesUse ReturnValues if you want to get the item attributes as they appear before or after they are successfully updated.

--return-consumed-capacityDetermines the level of detail about either provisioned or on-demand 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.

--return-item-collection-metricsDetermines whether item collection metrics are returned.

Contents of key.json:

{
    "Artist": {"S": "Acme Band"},
    "SongTitle": {"S": "Happy Day"}
}

Contents of expression-attribute-names.json:

{
    "#Y":"Year", "#AT":"AlbumTitle"
}

Contents of expression-attribute-values.json:

{
    ":y":{"N": "2015"},
    ":t":{"S": "Louder Than Ever"}
}

Its output, shortened

{
    "Attributes": {
        "AlbumTitle": {
            "S": "Louder Than Ever"
        },
        "Awards": {
            "N": "10"
        },
        "Artist": {
            "S": "Acme Band"
        },
        "Year": {
            "N": "2015"
        },
        "SongTitle": {
            "S": "Happy Day"
        }
    },
    "ConsumedCapacity": {
        "TableName": "MusicCollection",
        "CapacityUnits": 3.0
    },
    "ItemCollectionMetrics": {
        "ItemCollectionKey": {
            "Artist": {
                "S": "Acme Band"
            }
        },
        "SizeEstimateRangeGB": [
            0.0,
… 4 more lines

For more information, see Writing an Item in the Amazon DynamoDB Developer Guide.

Example 2: To update an item conditionally

The following update-item example updates an item in the MusicCollection table, but only if the existing item does not already have a Year attribute.

aws dynamodb update-item --table-name MusicCollection --key file://key.json --update-expression "SET #Y = :y, #AT = :t" --expression-attribute-names file://expression-attribute-names.json --expression-attribute-values file://expression-attribute-values.json --condition-expression "attribute_not_exists(#Y)"

Identify

--table-nameThe name of the table containing the item to update.

--keyThe primary key of the item to be updated.

--update-expressionAn expression that defines one or more attributes to be updated, the action to be performed on them, and new values for them.

--expression-attribute-namesOne or more substitution tokens for attribute names in an expression.

--expression-attribute-valuesOne or more values that can be substituted in an expression.

--condition-expressionA condition that must be satisfied in order for a conditional update to succeed.

Contents of key.json:

{
    "Artist": {"S": "Acme Band"},
    "SongTitle": {"S": "Happy Day"}
}

Contents of expression-attribute-names.json:

{
    "#Y":"Year",
    "#AT":"AlbumTitle"
}

Contents of expression-attribute-values.json:

{
    ":y":{"N": "2015"},
    ":t":{"S": "Louder Than Ever"}
}

This command produces no output. DynamoDB updates the item only if it does not already have a Year attribute. If the item already has a Year attribute, the command fails with the following error.

An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed

For more information, see Writing an Item in the Amazon DynamoDB Developer Guide.

Options

11 in the AWS CLI reference

--condition-expressionA condition that must be satisfied in order for a conditional update to succeed.

--conditional-operator, --attribute-updates, --expectedThis is a legacy parameter.

--expression-attribute-namesOne or more substitution tokens for attribute names in an expression.

--expression-attribute-valuesOne or more values that can be substituted in an expression.

--keyThe primary key of the item to be updated.

--return-item-collection-metricsDetermines whether item collection metrics are returned.

--return-values-on-condition-check-failureAn optional parameter that returns the item attributes for an UpdateItem operation that failed a condition check.

--return-valuesUse ReturnValues if you want to get the item attributes as they appear before or after they are successfully updated.

--table-nameThe name of the table containing the item to update.

--update-expressionAn expression that defines one or more attributes to be updated, the action to be performed on them, and new values for them.