Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

PutItem method

Written by
Updated at April 24, 2026

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 such item, the method creates it.

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

It may return the attribute values as they were 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 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 values for both the partition key and the sort key.
Values for string and binary attributes can be empty.

Type: Object of the AttributeValue type
Length: 1 to 65,535 characters.
Required: Yes
TableName Name of the table with the item in question.
It may contain a path in the hierarchical directory structure in path/to/table format.

Type: String
Length: 3 to 255 characters.
Template: [a-zA-Z0-9_.-]+
Required: Yes
ConditionExpression Condition for replacing the item. The method will be triggered only if the condition is met.
The condition consists of:
  • Functions: attribute_exists | attribute_not_exists | attribute_type | contains | begins_with | size. Names are case-sensitive.
  • Comparison operators: = | <> | < | > | <= | >= | BETWEEN | IN.
  • Logical operators: AND | OR | NOT.

Type: String
Required: No
ExpressionAttributeNames Placeholder for an attribute name in an expression. The placeholder must start with the hash character, #.
You can use it in the following cases:
  • To specify an attribute whose name conflicts with a reserved word.
  • As a variable, if the attribute name is used multiple times in an expression.
  • To prevent incorrect interpretation of special characters in the attribute name.
For example, the Percentile attribute name conflicts with the reserved word, so you cannot use it explicitly in an expression. To fix this issue, specify the {"#P":"Percentile"} placeholder in the ExpressionAttributeNames parameter, and then, further on, use #P instead of the real attribute name.

Type: String
Length: 1 to 65,535 characters.
Required: No
ExpressionAttributeValues Placeholder for an attribute name in an expression, same as 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"} }. Now you can use them in the expression: ProductStatus IN (:avail, :back, :disc)

Type: String of the AttributeValue type
Required: No
ReturnConsumedCapacity Sets 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 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.
You will get data 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 the attribute values before the update.
It is returned only if you provide ReturnValues set to ALL_OLD in the request.

Type: Associative array of the AttributeValue type.
Length: 1 to 65,535 characters.
ConsumedCapacity Capacity units consumed by a delete operation.
It is returned only if you provide ReturnConsumedCapacity set to TOTAL 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 Your request rate is too high. Try to reduce the frequency of requests.
If their number is not too large, Managed Service for YDB will try to process them all.

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

HTTP status code: 400
ResourceNotFoundException The requested table does not exist.

HTTP status code: 400
TransactionConflictException The operation is rejected because there is an ongoing transaction for the item.

HTTP status code: 400

There may be some common errors as well shared by all methods.

Previous
ListTables
Next
Query