Class UpdateItemCommandProtected

Edits an existing item's attributes, or adds a new item to the table if it does not already exist. You can put, delete, or add attribute values. You can also perform a conditional update on an existing item (insert a new attribute name-value pair if it doesn't exist, or replace an existing name-value pair if it has certain expected attribute values).

You can also return the item's attribute values in the same UpdateItem operation using the ReturnValues parameter.

Example

Use a bare-bones client and the command you need to make an API call.

import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import
// const { DynamoDBClient, UpdateItemCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import
const client = new DynamoDBClient(config);
const input = { // UpdateItemInput
  TableName: "STRING_VALUE", // required
  Key: { // Key // required
    "<keys>": { // AttributeValue Union: only one key present
      S: "STRING_VALUE",
      N: "STRING_VALUE",
      B: "BLOB_VALUE",
      SS: [ // StringSetAttributeValue
        "STRING_VALUE",
      ],
      NS: [ // NumberSetAttributeValue
        "STRING_VALUE",
      ],
      BS: [ // BinarySetAttributeValue
        "BLOB_VALUE",
      ],
      M: { // MapAttributeValue
        "<keys>": {//  Union: only one key present
          S: "STRING_VALUE",
          N: "STRING_VALUE",
          B: "BLOB_VALUE",
          SS: [
            "STRING_VALUE",
          ],
          NS: [
            "STRING_VALUE",
          ],
          BS: [
            "BLOB_VALUE",
          ],
          M: {
            "<keys>": "<AttributeValue>",
          },
          L: [ // ListAttributeValue
            "<AttributeValue>",
          ],
          NULL: true || false,
          BOOL: true || false,
        },
      },
      L: [
        "<AttributeValue>",
      ],
      NULL: true || false,
      BOOL: true || false,
    },
  },
  AttributeUpdates: { // AttributeUpdates
    "<keys>": { // AttributeValueUpdate
      Value: "<AttributeValue>",
      Action: "ADD" || "PUT" || "DELETE",
    },
  },
  Expected: { // ExpectedAttributeMap
    "<keys>": { // ExpectedAttributeValue
      Value: "<AttributeValue>",
      Exists: true || false,
      ComparisonOperator: "EQ" || "NE" || "IN" || "LE" || "LT" || "GE" || "GT" || "BETWEEN" || "NOT_NULL" || "NULL" || "CONTAINS" || "NOT_CONTAINS" || "BEGINS_WITH",
      AttributeValueList: [ // AttributeValueList
        "<AttributeValue>",
      ],
    },
  },
  ConditionalOperator: "AND" || "OR",
  ReturnValues: "NONE" || "ALL_OLD" || "UPDATED_OLD" || "ALL_NEW" || "UPDATED_NEW",
  ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE",
  ReturnItemCollectionMetrics: "SIZE" || "NONE",
  UpdateExpression: "STRING_VALUE",
  ConditionExpression: "STRING_VALUE",
  ExpressionAttributeNames: { // ExpressionAttributeNameMap
    "<keys>": "STRING_VALUE",
  },
  ExpressionAttributeValues: { // ExpressionAttributeValueMap
    "<keys>": "<AttributeValue>",
  },
};
const command = new UpdateItemCommand(input);
const response = await client.send(command);
// { // UpdateItemOutput
//   Attributes: { // AttributeMap
//     "<keys>": { // AttributeValue Union: only one key present
//       S: "STRING_VALUE",
//       N: "STRING_VALUE",
//       B: "BLOB_VALUE",
//       SS: [ // StringSetAttributeValue
//         "STRING_VALUE",
//       ],
//       NS: [ // NumberSetAttributeValue
//         "STRING_VALUE",
//       ],
//       BS: [ // BinarySetAttributeValue
//         "BLOB_VALUE",
//       ],
//       M: { // MapAttributeValue
//         "<keys>": {//  Union: only one key present
//           S: "STRING_VALUE",
//           N: "STRING_VALUE",
//           B: "BLOB_VALUE",
//           SS: [
//             "STRING_VALUE",
//           ],
//           NS: [
//             "STRING_VALUE",
//           ],
//           BS: [
//             "BLOB_VALUE",
//           ],
//           M: {
//             "<keys>": "<AttributeValue>",
//           },
//           L: [ // ListAttributeValue
//             "<AttributeValue>",
//           ],
//           NULL: true || false,
//           BOOL: true || false,
//         },
//       },
//       L: [
//         "<AttributeValue>",
//       ],
//       NULL: true || false,
//       BOOL: true || false,
//     },
//   },
//   ConsumedCapacity: { // ConsumedCapacity
//     TableName: "STRING_VALUE",
//     CapacityUnits: Number("double"),
//     ReadCapacityUnits: Number("double"),
//     WriteCapacityUnits: Number("double"),
//     Table: { // Capacity
//       ReadCapacityUnits: Number("double"),
//       WriteCapacityUnits: Number("double"),
//       CapacityUnits: Number("double"),
//     },
//     LocalSecondaryIndexes: { // SecondaryIndexesCapacityMap
//       "<keys>": {
//         ReadCapacityUnits: Number("double"),
//         WriteCapacityUnits: Number("double"),
//         CapacityUnits: Number("double"),
//       },
//     },
//     GlobalSecondaryIndexes: {
//       "<keys>": {
//         ReadCapacityUnits: Number("double"),
//         WriteCapacityUnits: Number("double"),
//         CapacityUnits: Number("double"),
//       },
//     },
//   },
//   ItemCollectionMetrics: { // ItemCollectionMetrics
//     ItemCollectionKey: { // ItemCollectionKeyAttributeMap
//       "<keys>": "<AttributeValue>",
//     },
//     SizeEstimateRangeGB: [ // ItemCollectionSizeEstimateRange
//       Number("double"),
//     ],
//   },
// };

Param

UpdateItemCommandInput

Returns

UpdateItemCommandOutput

See

• UpdateItemCommandInput for command's input shape.
• UpdateItemCommandOutput for command's response shape.
• config for DynamoDBClient's config shape.

Throws

ConditionalCheckFailedException (client fault)

A condition specified in the operation could not be evaluated.

Throws

InternalServerError (server fault)

An error occurred on the server side.

Throws

InvalidEndpointException (client fault)

Throws

ItemCollectionSizeLimitExceededException (client fault)

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

Throws

ProvisionedThroughputExceededException (client fault)

Your request rate is too high. The Amazon Web Services SDKs for DynamoDB automatically retry requests that receive this exception. Your request is eventually successful, unless your retry queue is too large to finish. Reduce the frequency of requests and use exponential backoff. For more information, go to Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide.

Throws

RequestLimitExceeded (client fault)

Throughput exceeds the current throughput quota for your account. Please contact Amazon Web Services Support to request a quota increase.

Throws

ResourceNotFoundException (client fault)

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

Throws

TransactionConflictException (client fault)

Operation was rejected because there is an ongoing transaction for the item.

Throws

DynamoDBServiceException

Base exception class for all service exceptions from DynamoDB service.

Example

To update an item in a table

// This example updates an item in the Music 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.
const input = {
  "ExpressionAttributeNames": {
    "#AT": "AlbumTitle",
    "#Y": "Year"
  },
  "ExpressionAttributeValues": {
    ":t": {
      "S": "Louder Than Ever"
    },
    ":y": {
      "N": "2015"
    }
  },
  "Key": {
    "Artist": {
      "S": "Acme Band"
    },
    "SongTitle": {
      "S": "Happy Day"
    }
  },
  "ReturnValues": "ALL_NEW",
  "TableName": "Music",
  "UpdateExpression": "SET #Y = :y, #AT = :t"
};
const command = new UpdateItemCommand(input);
const response = await client.send(command);
/* response ==
{
  "Attributes": {
    "AlbumTitle": {
      "S": "Louder Than Ever"
    },
    "Artist": {
      "S": "Acme Band"
    },
    "SongTitle": {
      "S": "Happy Day"
    },
    "Year": {
      "N": "2015"
    }
  }
}
*/
// example id: to-update-an-item-in-a-table-1476118250055