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

TransactWriteItems method

Written by
Updated at April 24, 2026

Performs a synchronous write operation that groups up to 25 actions. You can work with items from different tables, but you can only perform one action on a single item per request.

The total size of all items may not exceed 4 MB.

The method is atomic, i.e., either all actions succeed or all of them fail. For rejection reasons, see the TransactionCanceledException error description.

You can perform the following actions:

  • Put: Write a new item.
  • Update: Update an existing item.
  • Delete: Delete an existing item.
  • ConditionCheck: Condition for checking if an item exists or the state of its attributes.

Request

The request contains data in JSON format.

{
   "ReturnConsumedCapacity": "string",
   "TransactItems": [
      {
         "ConditionCheck": {
            "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" ]
               }
            },
            "Key": {
               "string" : {
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [
                     "AttributeValue"
                  ],
                  "M": {
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Delete": {
            "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" ]
               }
            },
            "Key": {
               "string" : {
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [
                     "AttributeValue"
                  ],
                  "M": {
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Put": {
            "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" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Update": {
            "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" ]
               }
            },
            "Key": {
               "string" : {
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [
                     "AttributeValue"
                  ],
                  "M": {
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string",
            "UpdateExpression": "string"
         }
      }
   ]
}

Parameters

Parameter Description
TransactItems Ordered array of objects of the TransactWriteItem type, each of which contains a Put, Update, Delete, or ConditionCheck operation. You can work with items from different tables, but you can only use each item in a single request once.

Type: Array of TransactWriteItem objects
Array items: 1 to 25 items.
Required: Yes
ClientRequestToken This parameter is not supported. Regardless of token values, all method calls are idempotent. This means that repeated method calls will have the same effect as a single call.
Although the server state will not change, responses may be different. If the ReturnConsumedCapacity parameter is set, the first request will return the number of write capacity units. Subsequent requests with the same token will return the number of read capacity units.
The token is valid within 10 minutes of completing the first request. After that, any request with the same token is considered new.
If you send the same token but with different parameters within 10 minutes, the method will return the IdempotentParameterMismatch exception.

Type: String
Length: 1 to 36 characters.
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

Response

If successful, HTTP code 200 is returned.
You will get data in JSON format.

{
   "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
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
IdempotentParameterMismatchException Request rejected as containing an idempotent token with different parameters.

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

HTTP status code: 500
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
TransactionCanceledException The entire request was canceled.
This may happen in the following cases:
  • A condition set in one of the expressions is not met.
  • Multiple actions in a single request target the same item.
  • The provisioned capacity is insufficient to complete the transaction.
  • The size of an individual item is too large (more than 400 KB). A similar error may also occur because of changes made by the transaction.
  • The total size of all items exceeds 4 MB.
  • A user error occurred, such as invalid data format.

HTTP status code: 400
TransactionInProgressException There is an ongoing transaction with the specified request token.

HTTP status code: 400

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

Previous
TransactGetItems
Next
UpdateItem