Amazon DynamoDB
API Reference (API Version 2012-08-10)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

BatchWriteItem

The BatchWriteItem operation puts or deletes multiple items in one or more tables. A single call to BatchWriteItem can write up to 1 MB of data, which can comprise as many as 25 put or delete requests. Individual items to be written can be as large as 64 KB.

Note

BatchWriteItem cannot update items. To update items, use the UpdateItem API.

The individual PutItem and DeleteItem operations specified in BatchWriteItem are atomic; however BatchWriteItem as a whole is not. If any requested operations fail because the table's provisioned throughput is exceeded or an internal processing failure occurs, the failed operations are returned in the UnprocessedItems response parameter. You can investigate and optionally resend the requests. Typically, you would call BatchWriteItem in a loop. Each iteration would check for unprocessed items and submit a new BatchWriteItem request with those unprocessed items until all items have been processed.

Note that if none of the items can be processed due to insufficient provisioned throughput on all of the tables in the request, then BatchGetItem will throw a ProvisionedThroughputExceededException.

Important

If DynamoDB returns any unprocessed items, you should retry the batch operation on those items. However, we strongly recommend that you use an exponential backoff algorithm. If you retry the batch operation immediately, the underlying read or write requests can still fail due to throttling on the individual tables. If you delay the batch operation using exponential backoff, the individual requests in the batch are much more likely to succeed.

For more information, go to Batch Operations and Error Handling in the Amazon DynamoDB Developer Guide.

With BatchWriteItem, you can efficiently write or delete large amounts of data, such as from Amazon Elastic MapReduce (EMR), or copy data from another database into DynamoDB. In order to improve performance with these large-scale operations, BatchWriteItem does not behave in the same way as individual PutItem and DeleteItem calls would For example, you cannot specify conditions on individual put and delete requests, and BatchWriteItem does not return deleted items in the response.

If you use a programming language that supports concurrency, such as Java, you can use threads to write items in parallel. Your application must include the necessary logic to manage the threads. With languages that don't support threading, such as PHP, you must update or delete items one at a time. In both situations, BatchWriteItem provides an alternative where the API performs the specified put and delete operations in parallel, giving you the power of the thread pool approach without having to introduce complexity into your application.

Parallel processing reduces latency, but each specified put and delete request consumes the same number of write capacity units whether it is processed in parallel or not. Delete operations on nonexistent items consume one write capacity unit.

If one or more of the following is true, DynamoDB rejects the entire batch write operation:

  • One or more tables specified in the BatchWriteItem request does not exist.

  • Primary key attributes specified on an item in the request do not match those in the corresponding table's primary key schema.

  • You try to perform multiple operations on the same item in the same BatchWriteItem request. For example, you cannot put and delete the same item in the same BatchWriteItem request.

  • The total request size exceeds 1 MB.

  • Any individual item in a batch exceeds 64 KB.

Request Syntax

{
    "RequestItems": 
        {
            "string" :
                [
                    {
                        "DeleteRequest": {
                            "Key": 
                                {
                                    "string" :
                                        {
                                            "B": "blob",
                                            "BS": [
                                                "blob"
                                            ],
                                            "N": "string",
                                            "NS": [
                                                "string"
                                            ],
                                            "S": "string",
                                            "SS": [
                                                "string"
                                            ]
                                        }
                                }
                        },
                        "PutRequest": {
                            "Item": 
                                {
                                    "string" :
                                        {
                                            "B": "blob",
                                            "BS": [
                                                "blob"
                                            ],
                                            "N": "string",
                                            "NS": [
                                                "string"
                                            ],
                                            "S": "string",
                                            "SS": [
                                                "string"
                                            ]
                                        }
                                }
                        }
                    }
                ]
        },
    "ReturnConsumedCapacity": "string",
    "ReturnItemCollectionMetrics": "string"
}
			

Request Parameters

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

RequestItems

A map of one or more table names and, for each table, a list of operations to be performed (DeleteRequest or PutRequest). Each element in the map consists of the following:

  • DeleteRequest - Perform a DeleteItem operation on the specified item. The item to be deleted is identified by a Key subelement:

    • Key - A map of primary key attribute values that uniquely identify the item. Each entry in this map consists of an attribute name and an attribute value. For each primary key, you must provide all of the key attributes. For example, with a hash type primary key, you only need to specify the hash attribute. For a hash-and-range type primary key, you must specify both the hash attribute and the range attribute.

  • PutRequest - Perform a PutItem operation on the specified item. The item to be put is identified by an Item subelement:

    • Item - A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value. Attribute values must not be null; string and binary type attributes must have lengths greater than zero; and set type attributes must not be empty. Requests that contain empty values will be rejected with a ValidationException.

      If you specify any attributes that are part of an index key, then the data types for those attributes must match those of the schema in the table's attribute definition.

Type: String to WriteRequest object map

Length constraints: Minimum length of 1. Maximum length of 25.

Required: Yes

ReturnConsumedCapacity

If set to TOTAL, the response includes ConsumedCapacity data for tables and indexes. If set to INDEXES, the response includes ConsumedCapacity for indexes. If set to NONE (the default), ConsumedCapacity is not included in the response.

Type: String

Valid Values: INDEXES | TOTAL | NONE

Required: No

ReturnItemCollectionMetrics

If set to SIZE, statistics about item collections, if any, that were modified during the operation are returned in the response. If set to NONE (the default), no statistics are returned.

Type: String

Valid Values: SIZE | NONE

Required: No

Response Syntax

{
    "ConsumedCapacity": [
        {
            "CapacityUnits": "number",
            "GlobalSecondaryIndexes": 
                {
                    "string" :
                        {
                            "CapacityUnits": "number"
                        }
                },
            "LocalSecondaryIndexes": 
                {
                    "string" :
                        {
                            "CapacityUnits": "number"
                        }
                },
            "Table": {
                "CapacityUnits": "number"
            },
            "TableName": "string"
        }
    ],
    "ItemCollectionMetrics": 
        {
            "string" :
                [
                    {
                        "ItemCollectionKey": 
                            {
                                "string" :
                                    {
                                        "B": "blob",
                                        "BS": [
                                            "blob"
                                        ],
                                        "N": "string",
                                        "NS": [
                                            "string"
                                        ],
                                        "S": "string",
                                        "SS": [
                                            "string"
                                        ]
                                    }
                            },
                        "SizeEstimateRangeGB": [
                            "number"
                        ]
                    }
                ]
        },
    "UnprocessedItems": 
        {
            "string" :
                [
                    {
                        "DeleteRequest": {
                            "Key": 
                                {
                                    "string" :
                                        {
                                            "B": "blob",
                                            "BS": [
                                                "blob"
                                            ],
                                            "N": "string",
                                            "NS": [
                                                "string"
                                            ],
                                            "S": "string",
                                            "SS": [
                                                "string"
                                            ]
                                        }
                                }
                        },
                        "PutRequest": {
                            "Item": 
                                {
                                    "string" :
                                        {
                                            "B": "blob",
                                            "BS": [
                                                "blob"
                                            ],
                                            "N": "string",
                                            "NS": [
                                                "string"
                                            ],
                                            "S": "string",
                                            "SS": [
                                                "string"
                                            ]
                                        }
                                }
                        }
                    }
                ]
        }
}
			

Response Elements

The following data is returned in JSON format by the service.

ConsumedCapacity

The capacity units consumed by the operation.

Each element consists of:

  • TableName - The table that consumed the provisioned throughput.

  • CapacityUnits - The total number of capacity units consumed.

Type: array of ConsumedCapacity objects

ItemCollectionMetrics

A list of tables that were processed by BatchWriteItem and, for each table, information about any item collections that were affected by individual DeleteItem or PutItem operations.

Each entry consists of the following subelements:

  • ItemCollectionKey - The hash key value of the item collection. This is the same as the hash key of the item.

  • SizeEstimateRange - An estimate of item collection size, expressed in GB. This is a two-element array containing a lower bound and an upper bound for the estimate. The estimate includes the size of all the items in the table, plus the size of all attributes projected into all of the local secondary indexes on the table. Use this estimate to measure whether a local secondary index is approaching its size limit.

    The estimate is subject to change over time; therefore, do not rely on the precision or accuracy of the estimate.

Type: String to ItemCollectionMetrics object map

UnprocessedItems

A map of tables and requests against those tables that were not processed. The UnprocessedItems value is in the same form as RequestItems, so you can provide this value directly to a subsequent BatchGetItem operation. For more information, see RequestItems in the Request Parameters section.

Each UnprocessedItems entry consists of a table name and, for that table, a list of operations to perform (DeleteRequest or PutRequest).

  • DeleteRequest - Perform a DeleteItem operation on the specified item. The item to be deleted is identified by a Key subelement:

    • Key - A map of primary key attribute values that uniquely identify the item. Each entry in this map consists of an attribute name and an attribute value.

  • PutRequest - Perform a PutItem operation on the specified item. The item to be put is identified by an Item subelement:

    • Item - A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value. Attribute values must not be null; string and binary type attributes must have lengths greater than zero; and set type attributes must not be empty. Requests that contain empty values will be rejected with a ValidationException.

      If you specify any attributes that are part of an index key, then the data types for those attributes must match those of the schema in the table's attribute definition.

If there are no unprocessed items remaining, the response contains an empty UnprocessedItems map.

Type: String to WriteRequest object map

Length constraints: Minimum length of 1. Maximum length of 25.

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

ItemCollectionSizeLimitExceededException

An item collection is too large. This exception is only returned for tables that have one or more local secondary indexes.

HTTP Status Code: 400

ProvisionedThroughputExceededException

The request rate is too high, or the request is too large, for the available throughput to accommodate. The AWS SDKs automatically retry requests that receive this exception; therefore, your request will eventually succeed, unless the request is too large or your retry queue is too large to finish. Reduce the frequency of requests by using the strategies listed in Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide.

HTTP Status Code: 400

ResourceNotFoundException

The operation tried to access a nonexistent table or index. The resource may not be specified correctly, or its status may not be ACTIVE.

HTTP Status Code: 400

Examples

Multiple Operations on One Table

This example writes several items to the Forum table. The response shows that the final put operation failed, possibly because the application exceeded the provisioned throughput on the table. The UnprocessedItems object shows the unsuccessful put request. The application can call BatchWriteItem again to address such unprocessed requests.

Sample Request

POST / HTTP/1.1
Host: dynamodb.<region>.<domain>;
X-Amz-Date: <Date>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-length;content-type;host;user-agent;x-amz-content-sha256;x-amz-date;x-amz-target, Signature=<Signature>
User-Agent: <UserAgentString>
x-amz-content-sha256: <PayloadHash>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>     
Connection: Keep-Alive X-Amz-Target: DynamoDB_20120810.BatchWriteItem 

{
    "RequestItems": {
        "Forum": [
            {
                "PutRequest": {
                    "Item": {
                        "Name": {
                            "S": "Amazon DynamoDB"
                        },
                        "Category": {
                            "S": "Amazon Web Services"
                        }
                    }
                }
            },
            {
                "PutRequest": {
                    "Item": {
                        "Name": {
                            "S": "Amazon RDS"
                        },
                        "Category": {
                            "S": "Amazon Web Services"
                        }
                    }
                }
            },
            {
                "PutRequest": {
                    "Item": {
                        "Name": {
                            "S": "Amazon Redshift"
                        },
                        "Category": {
                            "S": "Amazon Web Services"
                        }
                    }
                }
            },
            {
                "PutRequest": {
                    "Item": {
                        "Name": {
                            "S": "Amazon ElastiCache"
                        },
                        "Category": {
                            "S": "Amazon Web Services"
                        }
                    }
                }
            }
        ]
    },
    "ReturnConsumedCapacity": "TOTAL"
}
        

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId> 
x-amz-crc32: <Checksum>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
Date: <Date>
 {
    "UnprocessedItems": {
        "Forum": [
            {
                "PutRequest": {
                    "Item": {
                        "Name": {
                            "S": "Amazon ElastiCache"
                        },
                        "Category": {
                            "S": "Amazon Web Services"
                        }
                    }
                }
            }
        ]
    },
    "ConsumedCapacity": [
        {
            "TableName": "Forum",
            "CapacityUnits": 3
        }
    ]
}