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

BatchWriteItem method

Written by
Updated at April 24, 2026

Writes items to or deletes them from tables.
With a single call, you can write up to 16 MB of data, including up to 25 put or delete requests. Each item can be up to 400 KB in size.

The BatchWriteItem method cannot update items. Use UpdateItem instead.

Separate PutItem and DeleteItem operations within BatchWriteItem are atomic. However, the method as a whole is not atomic.

If none of the items is processed because there is not enough throughput, the method will return the ProvisionedThroughputExceededException error. If at least one item is processed, the method will complete successfully, while the unprocessed items will be returned under UnprocessedItems.

An entire batch write operation may be rejected in the following cases:

  • The table you provided in the request does not exist.
  • Primary key attributes specified in the request do not match those in the table's primary key schema.
  • You try to perform multiple operations with the same item within the same request.
  • Your request contains at least two items with identical hash and range keys.
  • There are more than 25 requests in the batch.
  • Any individual batch item exceeds 400 KB.
  • The total request size exceeds 16 MB.

Request

The request contains data in JSON format.

{
   "RequestItems": {
      "string" : [
         {
            "DeleteRequest": {
               "Key": {
                  "string" : {
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [
                        "AttributeValue"
                     ],
                     "M": {
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            },
            "PutRequest": {
               "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"
}

Parameters

Parameter Description
RequestItems Associative array of tables and table requests to run.
Each item consists of a table name and a list of operations to run (DeleteRequest or PutRequest).
  • DeleteRequest: Perform a DeleteItem operation with the specified item. The item to delete is identified by the Key parameter and nested item:
    • Key: Associative array of primary key attribute values that uniquely identify the item. Each record consists of an attribute name and attribute value.
      For each primary key, specify all the key attributes. For a simple primary key, you only need to specify its value. For a composite primary key, specify values for both the partition key and the sort key.
  • PutRequest: Perform a PutItem operation with the specified item. The item to put is identified by the Item parameter and nested item:
    • Item: Associative array of attributes and their values. Each record consists of an attribute name and attribute value. Attribute values must not be null. String and binary type attributes must be greater than zero in length. Set type attributes must not be empty. Requests containing empty values are rejected with ValidationException.
    Type: Associative array of the WriteRequest type.
    Number of records: Up to 25 items.
    Key length: 3 to 255 characters.
    Template: [a-zA-Z0-9_.-]+
    Array size: 1 to 25 items.
    Required: Yes
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
      }
   ],
   "UnprocessedItems": {
      "string" : [
         {
            "DeleteRequest": {
               "Key": {
                  "string" : {
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [
                        "AttributeValue"
                     ],
                     "M": {
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            },
            "PutRequest": {
               "Item": {
                  "string" : {
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [
                        "AttributeValue"
                     ],
                     "M": {
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            }
         }
      ]
   }
}

Parameters

Parameter Description
ConsumedCapacity Consumed capacity units.
It is returned only if you provide ReturnConsumedCapacity set to TOTAL in the request.
It consists of:
  • TableName: Table that consumes the provisioned throughput capacity.
  • CapacityUnits: Total number of capacity units consumed.

Type: Array of ConsumedCapacity objects
UnprocessedItems Associative array of tables and unprocessed table requests. The values have the format you set in the RequestItems parameter. You can reuse these values in a subsequent request.
If there are no unprocessed items left, the UnprocessedItems response parameter will be empty.

Type: Associative array of the WriteRequest type.
Number of records: Up to 25 items.
Key length: 3 to 255 characters.
Template: [a-zA-Z0-9_.-]+
Array size: 1 to 25 items.

Errors

Parameter Description
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

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

Previous
BatchGetItem
Next
CreateTable