PutItem method

Written by

Updated at February 10, 2023

Request
- Parameters
Response
- Parameters
Errors

Replaces an item in a table or creates a new one. If the item with the specified primary key already exists, the method replaces it with a new item. If there is no item, the method creates it.

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

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

Request

The request contains data in JSON format.

{
   "ConditionalOperator": "string",
   "ConditionExpression": "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" ]
      }
   },
   "Item": {
      "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"
}

Parameters

Parameter	Description
`Item`	An associative array of attributes of the key/value type. Only primary key attributes are required, but you can specify other attributes, too. For a primary key, specify all its key attributes. For a simple key, you only need to specify its value. For a composite primary key, specify the value of the partition key and the sort key. Values for string and binary attributes can be empty. Type: Object of the `AttributeValue` type Length: 1 - 65535 characters Required: Yes
`TableName`	Name of the table storing the item. May contain a path in the directory hierarchy like path/to/table. Type: String Length: 3 - 255 characters Pattern: [a-zA-Z0-9_.-]+ Requested: Yes
`ConditionExpression`	Condition for replacing 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 its update. Possible values: `NONE` (default): Do not return item attributes `ALL_OLD`: Return all attributes as they were before the item update Type: String Possible values: `NONE` \| `ALL_OLD` 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`	An associative array of the `AttributeValue` type containing attribute values before their update. Returned only if the request passed the `ReturnValues` parameter set to `ALL_OLD`. 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`	Failed to evaluate the condition specified in the operation. HTTP status code: 400
`InternalServerError`	An internal error occurred on the server side. HTTP status code: 500
`ItemCollectionSizeLimitExceededException`	Item collection size limit exceeded. This exception is only returned for tables with one or more local secondary indexes. HTTP status code: 400
`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. 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.

PutItem method

RequestRequest

ParametersParameters

ResponseResponse

ParametersParameters

ErrorsErrors

Was the article helpful?

Request

Parameters

Response

Parameters

Errors