Contact UsGet started

UpdateItem method

Written by
Updated at February 10, 2023

Updates the attributes of an existing item or adds a new item if it doesn't exist. You can update, delete, or add attribute values.

You can set an update condition. The method is then triggered only if the condition is met.

It may return the attribute values that were valid before or after the update.

Request

The request contains data in JSON format.

{
   "AttributeUpdates": {
      "string" : {
         "Action": "string",
         "Value": {
            "B": blob,
            "BOOL": boolean,
            "BS": [ blob ],
            "L": [
               "AttributeValue"
            ],
            "M": {
               "string" : "AttributeValue"
            },
            "N": "string",
            "NS": [ "string" ],
            "NULL": boolean,
            "S": "string",
            "SS": [ "string" ]
         }
      }
   },
   "ConditionExpression": "string",
   "Expected": {
      "string" : {
         "AttributeValueList": [
            {
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [
                  "AttributeValue"
               ],
               "M": {
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string",
         "Exists": boolean,
         "Value": {
            "B": blob,
            "BOOL": boolean,
            "BS": [ blob ],
            "L": [
               "AttributeValue"
            ],
            "M": {
               "string" : "AttributeValue"
            },
            "N": "string",
            "NS": [ "string" ],
            "NULL": boolean,
            "S": "string",
            "SS": [ "string" ]
         }
      }
   },
   "ExpressionAttributeNames": {
      "string" : "string"
   },
   "ExpressionAttributeValues": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "Key": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ReturnConsumedCapacity": "string",
   "ReturnValues": "string",
   "TableName": "string",
   "UpdateExpression": "string"
}

Parameters

Parameter Description
Key Primary key of the item to update, specify all the key attributes. For a simple primary key, you only need to specify its value. For a composite primary key, specify the value of the partition key and sort key.

Type: Associative array of the AttributeValue type.
Length: 1: 65535 characters.
Required: Yes
TableName Name of the table storing the item to update.
May contain a path in the directory hierarchy like path/to/table.

Type: String
Length: 3: 255 characters
Pattern: [a-zA-Z0-9_.-]+
Required: Yes
ConditionExpression Condition for updating the item. The method will trigger only if the condition is met.
The condition consists of:
  • A function: attribute_exists | attribute_not_exists | attribute_type | contains | begins_with | size. Names are case-sensitive.
  • A comparison operator: = | <> | < | > | <= | >= | BETWEEN | IN.
  • A logical operator: AND | OR | NOT.

Type: String
Required: No
ExpressionAttributeNames Placeholder that can be used in an expression instead of an attribute name. The placeholder must start with the hash character #.
Possible use cases:
  • If you need to specify an attribute whose name conflicts with the word reserved.
  • As a variable if the attribute name is used several times in an expression.
  • To prevent incorrect interpretation of special characters in the attribute name.
For example, the name of the Percentile attribute is in conflict with a reserved word and cannot be explicitly used in an expression. To get around this problem, in the ExpressionAttributeNames parameter, specify the placeholder: {"#P":"Percentile"}. Then, instead of the real attribute name, use #P.

Type: String
Length: 1: 65535 characters.
Required: No
ExpressionAttributeValues Placeholder that can be used in an expression instead of an attribute value, similar to ExpressionAttributeNames. The placeholder must start with a colon :.
For example, you need to check whether the value of the ProductStatus attribute was one of the following: Available | Backordered | Discontinued. To do this, first declare placeholders: { ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, ":disc":{"S":"Discontinued"} }. After that, you can use them in the expression: ProductStatus IN (:avail, :back, :disc)

Type: String of the AttributeValue type
Required: No
ReturnConsumedCapacity Indicates whether to return information about the consumed capacity.
  • TOTAL: Return.
  • NONE: Do not return.

Type: String
Possible values: TOTAL | NONE
Required: No
ReturnValues Use it if you need to get the attributes of an item before and after its update.
Possible values:
  • NONE (default): Do not return item attributes
  • ALL_OLD: Return all attributes as they were before the item update
  • UPDATED_OLD: Only return the updated attributes as they were before the update.
  • ALL_NEW: Return all attributes as they will be after the update.
  • UPDATED_NEW: Only return the updated attributes as they will be after the update.
No read capacity units are used in this case.
Returned values are strongly consistent.

Type: String
Possible values: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW
Required: No
UpdateExpression Expression to update. Specifies how and which attributes to update.
Possible actions:
  • SET: Sets the attribute to the specified value. If no attribute exists, it will be created.
    Supported functions:
    • if_not_exists (path, operand): Checks that the specified attribute doesn't exist. If no attribute is found at the specified path, the function calculates the specified operand.
    • list_append (operand, operand) evaluates to a list with a new element added to it. You can append the new element to the start or the end of the list by reversing the order of the operands.
    Function names are case-sensitive.
  • REMOVE: Removes attributes.
  • ADD: Adds a value to an attribute.
    F the attribute exists, the ADD function behavior depends on the attribute's data type:
    • If it's numeric, the addition operation is performed and the attribute value is added to the specified value. If the attribute or value didn't exist, then 0 is taken as the basis and used by the addition operation.
    • If the attribute is a set, the specified value is added to the set. Both sets (that in the attribute value and the one specified) must have the same data type.
  • DELETE Deletes an item from the set. Applicable to sets and top-level attributes only. You can't delete nested attributes.
    You can specify multiple items at a time.
A single expression may contain multiple actions, for example, SET a=:value1, b=:value2 DELETE :value3, :value4, :value5

Type: String
Required: No

Response

If successful, HTTP code 200 is returned.
The response is returned in JSON format.

{
   "Attributes": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ConsumedCapacity": {
      "CapacityUnits": number,
      "GlobalSecondaryIndexes": {
         "string" : {
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         }
      },
      "LocalSecondaryIndexes": {
         "string" : {
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         }
      },
      "ReadCapacityUnits": number,
      "Table": {
         "CapacityUnits": number,
         "ReadCapacityUnits": number,
         "WriteCapacityUnits": number
      },
      "TableName": "string",
      "WriteCapacityUnits": number
   }

}

Parameters

Parameter Description
Attributes Associative array of the AttributeValue type containing an item's representation before or after it's updated.
Returned only if the request passed the ReturnValues parameter that wasn't set to NONE.

Type: Associative array of the AttributeValue type
Length: 1: 65535 characters.
ConsumedCapacity Capacity units consumed by a delete operation.
Returned only if the ReturnConsumedCapacity parameter set to TOTAL is specified in the request.

Type: Object of the ConsumedCapacity type.

Errors

Parameter Description
ConditionalCheckFailedException Can't check the condition specified in the operation.

HTTP status code: 400
InternalServerError An internal error occurred on the server side.

HTTP status code: 500
ProvisionedThroughputExceededException You're sending requests too often. Try to increase the interval between requests.
If their number is not too large, Managed Service for YDB tries to process them all.

HTTP status code: 400
RequestLimitExceeded The bandwidth exceeds the set quota.

HTTP status code: 400
ResourceNotFoundException The specified table doesn't exist or its state is different from 'ACTIVE'.

HTTP status code: 400
TransactionConflictException The operation is rejected as a different transaction is in progress for the item.

HTTP status code: 400

There may be common errors as well. These are errors that are common to all methods.

Previous
TransactWriteItems
Next
UpdateTimeToLive