Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

BatchWriteItem method

Written by
Updated at February 27, 2023

Writes items to or deletes them from tables.
A single call 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.

BatchWriteItem can't update items. To do this, use the UpdateItem method.

The individual PutItem and DeleteItem operations used in BatchWriteItem are atomic. However, the method as a whole is not.

If none of the items can be processed because there is not enough throughput, the method returns a ProvisionedThroughputExceededException. If at least one item is processed, the action is successful and the unprocessed items are returned in the UnprocessedItems parameter.

The entire batch write operation can be rejected:

  • A table specified in the request doesn't exist.
  • Primary key attributes specified in the request don't match those in the table's primary key schema.
  • You try to perform multiple operations on the same item in 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 An associative array of tables and related requests to perform.
Each item consists of a table name and a list of operations to perform (DeleteRequest or PutRequest).
  • DeleteRequest: Perform a DeleteItem operation on the specified item. The item to delete is identified by the Key parameter and nested element:
    • Key: An associative array of primary key attributes that uniquely identify the item. Each entry 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 on the specified item. The item to be put is identified by the Item parameter and nested element:
    • Item: An associative array of attributes and their values. Each entry consists of an attribute name and attribute value. Attribute values must not be null. String and binary type attributes must have lengths greater than zero. Set type attributes must not be empty. Requests containing empty values are rejected with a ValidationException exception.
    Type: Associative array of the WriteRequest type.
    Number of entries: Up to 25 items.
    Key length: 3-255 characters.
    Pattern: [a-zA-Z0-9_.-]+
    Array size: 1-25 items.
    Required: Yes
ReturnConsumedCapacity Indicates 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.
The response is returned 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.
Returned only if the ReturnConsumedCapacity parameter set to TOTAL is specified in the request.
Consists of:
  • TableName: Table that consumes the allocated bandwidth.
  • CapacityUnits: Total number of capacity units consumed.

Type: Array of objects of the ConsumedCapacity type.
UnprocessedItems An associative array of tables and related requests that were not processed. The values are in the same form as they were set in RequestItems. You can reuse these values in a subsequent request.
If there are no unprocessed items left, the response contains an empty UnprocessedItems.

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

Errors

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

HTTP status code: 400

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

Previous
BatchGetItem
Next
CreateTable