BatchExecuteStatementCommand

Suggest an Edit

This operation allows you to perform batch reads or writes on data stored in DynamoDB, using PartiQL. Each read statement in a BatchExecuteStatement must specify an equality condition on all key attributes. This enforces that each SELECT statement in a batch returns at most a single item. For more information, see Running batch operations with PartiQL for DynamoDB  .

The entire batch must consist of either read statements or write statements, you cannot mix both in one batch.

A HTTP 200 response does not mean that all statements in the BatchExecuteStatement succeeded. Error details for individual statements can be found under the Error  field of the BatchStatementResponse for each statement.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { DynamoDBClient, BatchExecuteStatementCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import
// const { DynamoDBClient, BatchExecuteStatementCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import
const client = new DynamoDBClient(config);
const input = { // BatchExecuteStatementInput
  Statements: [ // PartiQLBatchRequest // required
    { // BatchStatementRequest
      Statement: "STRING_VALUE", // required
      Parameters: [ // PreparedStatementParameters
        { // AttributeValue Union: only one key present
          S: "STRING_VALUE",
          N: "STRING_VALUE",
          B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
          SS: [ // StringSetAttributeValue
            "STRING_VALUE",
          ],
          NS: [ // NumberSetAttributeValue
            "STRING_VALUE",
          ],
          BS: [ // BinarySetAttributeValue
            new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
          ],
          M: { // MapAttributeValue
            "<keys>": {//  Union: only one key present
              S: "STRING_VALUE",
              N: "STRING_VALUE",
              B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
              SS: [
                "STRING_VALUE",
              ],
              NS: [
                "STRING_VALUE",
              ],
              BS: [
                new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
              ],
              M: {
                "<keys>": "<AttributeValue>",
              },
              L: [ // ListAttributeValue
                "<AttributeValue>",
              ],
              NULL: true || false,
              BOOL: true || false,
            },
          },
          L: [
            "<AttributeValue>",
          ],
          NULL: true || false,
          BOOL: true || false,
        },
      ],
      ConsistentRead: true || false,
      ReturnValuesOnConditionCheckFailure: "ALL_OLD" || "NONE",
    },
  ],
  ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE",
};
const command = new BatchExecuteStatementCommand(input);
const response = await client.send(command);
// { // BatchExecuteStatementOutput
//   Responses: [ // PartiQLBatchResponse
//     { // BatchStatementResponse
//       Error: { // BatchStatementError
//         Code: "ConditionalCheckFailed" || "ItemCollectionSizeLimitExceeded" || "RequestLimitExceeded" || "ValidationError" || "ProvisionedThroughputExceeded" || "TransactionConflict" || "ThrottlingError" || "InternalServerError" || "ResourceNotFound" || "AccessDenied" || "DuplicateItem",
//         Message: "STRING_VALUE",
//         Item: { // AttributeMap
//           "<keys>": { // AttributeValue Union: only one key present
//             S: "STRING_VALUE",
//             N: "STRING_VALUE",
//             B: new Uint8Array(),
//             SS: [ // StringSetAttributeValue
//               "STRING_VALUE",
//             ],
//             NS: [ // NumberSetAttributeValue
//               "STRING_VALUE",
//             ],
//             BS: [ // BinarySetAttributeValue
//               new Uint8Array(),
//             ],
//             M: { // MapAttributeValue
//               "<keys>": {//  Union: only one key present
//                 S: "STRING_VALUE",
//                 N: "STRING_VALUE",
//                 B: new Uint8Array(),
//                 SS: [
//                   "STRING_VALUE",
//                 ],
//                 NS: [
//                   "STRING_VALUE",
//                 ],
//                 BS: [
//                   new Uint8Array(),
//                 ],
//                 M: {
//                   "<keys>": "<AttributeValue>",
//                 },
//                 L: [ // ListAttributeValue
//                   "<AttributeValue>",
//                 ],
//                 NULL: true || false,
//                 BOOL: true || false,
//               },
//             },
//             L: [
//               "<AttributeValue>",
//             ],
//             NULL: true || false,
//             BOOL: true || false,
//           },
//         },
//       },
//       TableName: "STRING_VALUE",
//       Item: {
//         "<keys>": "<AttributeValue>",
//       },
//     },
//   ],
//   ConsumedCapacity: [ // ConsumedCapacityMultiple
//     { // ConsumedCapacity
//       TableName: "STRING_VALUE",
//       CapacityUnits: Number("double"),
//       ReadCapacityUnits: Number("double"),
//       WriteCapacityUnits: Number("double"),
//       Table: { // Capacity
//         ReadCapacityUnits: Number("double"),
//         WriteCapacityUnits: Number("double"),
//         CapacityUnits: Number("double"),
//       },
//       LocalSecondaryIndexes: { // SecondaryIndexesCapacityMap
//         "<keys>": {
//           ReadCapacityUnits: Number("double"),
//           WriteCapacityUnits: Number("double"),
//           CapacityUnits: Number("double"),
//         },
//       },
//       GlobalSecondaryIndexes: {
//         "<keys>": {
//           ReadCapacityUnits: Number("double"),
//           WriteCapacityUnits: Number("double"),
//           CapacityUnits: Number("double"),
//         },
//       },
//     },
//   ],
// };

BatchExecuteStatementCommand Input

See BatchExecuteStatementCommandInput for more details

Parameter
Type
Description
Statements
Required
BatchStatementRequest[] | undefined

The list of PartiQL statements representing the batch to run.

ReturnConsumedCapacity
ReturnConsumedCapacity | undefined

Determines the level of detail about either provisioned or on-demand throughput consumption that is returned in the response:

  • INDEXES - The response includes the aggregate ConsumedCapacity for the operation, together with ConsumedCapacity for each table and secondary index that was accessed.

    Note that some operations, such as GetItem and BatchGetItem, do not access any indexes at all. In these cases, specifying INDEXES will only return ConsumedCapacity information for table(s).

  • TOTAL - The response includes only the aggregate ConsumedCapacity for the operation.

  • NONE - No ConsumedCapacity details are included in the response.

BatchExecuteStatementCommand Output

See BatchExecuteStatementCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
ConsumedCapacity
ConsumedCapacity[] | undefined

The capacity units consumed by the entire operation. The values of the list are ordered according to the ordering of the statements.

Responses
BatchStatementResponse[] | undefined

The response to each PartiQL statement in the batch. The values of the list are ordered according to the ordering of the request statements.

Throws

Name
Fault
Details
InternalServerError
server

An error occurred on the server side.

RequestLimitExceeded
client

Throughput exceeds the current throughput quota for your account. Please contact Amazon Web ServicesSupport  to request a quota increase.

DynamoDBServiceException
Base exception class for all service exceptions from DynamoDB service.