com.amazonaws.services.dynamodbv2.model
Class BatchWriteItemRequest

java.lang.Object
  com.amazonaws.AmazonWebServiceRequest
      com.amazonaws.services.dynamodbv2.model.BatchWriteItemRequest

All Implemented Interfaces:

java.io.Serializable

public class BatchWriteItemRequest
extends AmazonWebServiceRequest
implements java.io.Serializable

Container for the parameters to the BatchWriteItem operation.

This operation enables you to put or delete several items across multiple tables in a single API call.

To upload one item, you can use the PutItem API and to delete one item, you can use the DeleteItem API. However, when you want to upload or delete large amounts of data, such as uploading large amounts of data from Amazon Elastic MapReduce (EMR) or migrate data from another database into Amazon DynamoDB, this API offers an efficient alternative.

If you use a programming language that supports concurrency, such as Java, you can use threads to upload items in parallel. This adds complexity in your application to handle the threads. With other languages that don't support threading, such as PHP, you must upload or delete items one at a time. In both situations, the BatchWriteItem API 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 in your application.

Note that each individual put and delete specified in a BatchWriteItem operation costs the same in terms of consumed capacity units, however, the API performs the specified operations in parallel giving you lower latency. Delete operations on non-existent items consume 1 write capacity unit.

When using this API, note the following limitations:

• Maximum operations in a single request- You can specify a total of up to 25 put or delete operations; however, the total request size cannot exceed 1 MB (the HTTP payload).

• You can use the BatchWriteItem operation only to put and delete items. You cannot use it to update existing items.

• Not an atomic operation- The individual PutItem and DeleteItem operations specified in BatchWriteItem are atomic; however BatchWriteItem as a whole is a "best-effort" operation and not an atomic operation. That is, in a BatchWriteItem request, some operations might succeed and others might fail. The failed operations are returned in UnprocessedItems in the response. Some of these failures might be because you exceeded the provisioned throughput configured for the table or a transient failure such as a network error. You can investigate and optionally resend the requests. Typically, you call BatchWriteItem in a loop and in each iteration check for unprocessed items, and submit a new BatchWriteItem request with those unprocessed items.

• Does not return any items- The BatchWriteItem is designed for uploading large amounts of data efficiently. It does not provide some of the sophistication offered by APIs such as PutItem and DeleteItem . For example, the DeleteItem API supports ReturnValues in the request body to request the deleted item in the response. The BatchWriteItem operation does not return any items in the response.

• Unlike the PutItem and DeleteItem APIs, BatchWriteItem does not allow you to specify conditions on individual write requests in the operation.

• 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 have empty values will be rejected with a ValidationException .

Amazon DynamoDB rejects the entire batch write operation if any one of the following is true:

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

• If primary key attributes specified on an item in the request does not match the corresponding table's primary key schema.

• If 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.

• If the total request size exceeds the 1 MB request size (the HTTP payload) limit.

• If any individual item in a batch exceeds the 64 KB item size limit.

See Also:

AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest), Serialized Form

Constructor Summary

BatchWriteItemRequest()

Method Summary

boolean	equals(java.lang.Object obj)
java.util.Map<java.lang.String,java.util.List<WriteRequest>>	getRequestItems() A map of one or more table names and, for each table, a list of operations to perform (DeleteRequest or PutRequest).
java.lang.String	getReturnConsumedCapacity() Determines whether to include consumed capacity information in the output.
java.lang.String	getReturnItemCollectionMetrics() Indicates whether to return statistics about item collections, if any, that were modified during the operation.
int	hashCode()
void	setRequestItems(java.util.Map<java.lang.String,java.util.List<WriteRequest>> requestItems) A map of one or more table names and, for each table, a list of operations to perform (DeleteRequest or PutRequest).
void	setReturnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity) Determines whether to include consumed capacity information in the output.
void	setReturnConsumedCapacity(java.lang.String returnConsumedCapacity) Determines whether to include consumed capacity information in the output.
void	setReturnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics) Indicates whether to return statistics about item collections, if any, that were modified during the operation.
void	setReturnItemCollectionMetrics(java.lang.String returnItemCollectionMetrics) Indicates whether to return statistics about item collections, if any, that were modified during the operation.
java.lang.String	toString() Returns a string representation of this object; useful for testing and debugging.
BatchWriteItemRequest	withRequestItems(java.util.Map<java.lang.String,java.util.List<WriteRequest>> requestItems) A map of one or more table names and, for each table, a list of operations to perform (DeleteRequest or PutRequest).
BatchWriteItemRequest	withReturnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity) Determines whether to include consumed capacity information in the output.
BatchWriteItemRequest	withReturnConsumedCapacity(java.lang.String returnConsumedCapacity) Determines whether to include consumed capacity information in the output.
BatchWriteItemRequest	withReturnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics) Indicates whether to return statistics about item collections, if any, that were modified during the operation.
BatchWriteItemRequest	withReturnItemCollectionMetrics(java.lang.String returnItemCollectionMetrics) Indicates whether to return statistics about item collections, if any, that were modified during the operation.

Methods inherited from class com.amazonaws.AmazonWebServiceRequest

copyPrivateRequestParameters, getRequestClientOptions, getRequestCredentials, setRequestCredentials

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BatchWriteItemRequest

public BatchWriteItemRequest()

Method Detail

getRequestItems

public java.util.Map<java.lang.String,java.util.List<WriteRequest>> getRequestItems()

A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

Constraints:
Length: 1 - 25

Returns:

A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

setRequestItems

public void setRequestItems(java.util.Map<java.lang.String,java.util.List<WriteRequest>> requestItems)

A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

Constraints:
Length: 1 - 25

Parameters:

requestItems - A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

withRequestItems

public BatchWriteItemRequest withRequestItems(java.util.Map<java.lang.String,java.util.List<WriteRequest>> requestItems)

A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

Returns a reference to this object so that method calls can be chained together.

Constraints:
Length: 1 - 25

Parameters:

requestItems - A map of one or more table names and, for each 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:

  • 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 updated is identified by:

  • Item-A map of attributes and their values. Each entry in this map consists of an attribute name and an attribute value.

    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.

Returns:

A reference to this updated object so that method calls can be chained together.

getReturnConsumedCapacity

public java.lang.String getReturnConsumedCapacity()

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Constraints:
Allowed Values: TOTAL, NONE

Returns:

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

See Also:

ReturnConsumedCapacity

setReturnConsumedCapacity

public void setReturnConsumedCapacity(java.lang.String returnConsumedCapacity)

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Constraints:
Allowed Values: TOTAL, NONE

Parameters:

returnConsumedCapacity - Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

See Also:

ReturnConsumedCapacity

withReturnConsumedCapacity

public BatchWriteItemRequest withReturnConsumedCapacity(java.lang.String returnConsumedCapacity)

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Returns a reference to this object so that method calls can be chained together.

Constraints:
Allowed Values: TOTAL, NONE

Parameters:

returnConsumedCapacity - Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Returns:

A reference to this updated object so that method calls can be chained together.

See Also:

ReturnConsumedCapacity

setReturnConsumedCapacity

public void setReturnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity)

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Constraints:
Allowed Values: TOTAL, NONE

Parameters:

returnConsumedCapacity - Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

See Also:

ReturnConsumedCapacity

withReturnConsumedCapacity

public BatchWriteItemRequest withReturnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity)

Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Returns a reference to this object so that method calls can be chained together.

Constraints:
Allowed Values: TOTAL, NONE

Parameters:

returnConsumedCapacity - Determines whether to include consumed capacity information in the output. If this is set to TOTAL, then this information is shown in the output; otherwise, the consumed capacity information is not shown.

Returns:

A reference to this updated object so that method calls can be chained together.

See Also:

ReturnConsumedCapacity

getReturnItemCollectionMetrics

public java.lang.String getReturnItemCollectionMetrics()

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Constraints:
Allowed Values: SIZE, NONE

Returns:

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

See Also:

ReturnItemCollectionMetrics

setReturnItemCollectionMetrics

public void setReturnItemCollectionMetrics(java.lang.String returnItemCollectionMetrics)

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Constraints:
Allowed Values: SIZE, NONE

Parameters:

returnItemCollectionMetrics - Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

See Also:

ReturnItemCollectionMetrics

withReturnItemCollectionMetrics

public BatchWriteItemRequest withReturnItemCollectionMetrics(java.lang.String returnItemCollectionMetrics)

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Returns a reference to this object so that method calls can be chained together.

Constraints:
Allowed Values: SIZE, NONE

Parameters:

returnItemCollectionMetrics - Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Returns:

A reference to this updated object so that method calls can be chained together.

See Also:

ReturnItemCollectionMetrics

setReturnItemCollectionMetrics

public void setReturnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics)

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Constraints:
Allowed Values: SIZE, NONE

Parameters:

returnItemCollectionMetrics - Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

See Also:

ReturnItemCollectionMetrics

withReturnItemCollectionMetrics

public BatchWriteItemRequest withReturnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics)

Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Returns a reference to this object so that method calls can be chained together.

Constraints:
Allowed Values: SIZE, NONE

Parameters:

returnItemCollectionMetrics - Indicates whether to return statistics about item collections, if any, that were modified during the operation. The default for ReturnItemCollectionMetrics is NONE, meaning that no statistics will be returned. To obtain the statistics, set ReturnItemCollectionMetrics to SIZE.

Returns:

A reference to this updated object so that method calls can be chained together.

See Also:

ReturnItemCollectionMetrics

toString

public java.lang.String toString()

Returns a string representation of this object; useful for testing and debugging.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this object.

See Also:

Object.toString()

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object