Class ExecuteStatementCommandProtected

This operation allows you to perform reads and singleton writes on data stored in DynamoDB, using PartiQL.

For PartiQL reads (SELECT statement), if the total number of processed items exceeds the maximum dataset size limit of 1 MB, the read stops and results are returned to the user as a LastEvaluatedKey value to continue the read in a subsequent operation. If the filter criteria in WHERE clause does not match any data, the read will return an empty result set.

A single SELECT statement response can return up to the maximum number of items (if using the Limit parameter) or a maximum of 1 MB of data (and then apply any filtering to the results using WHERE clause). If LastEvaluatedKey is present in the response, you need to paginate the result set. If NextToken is present, you need to paginate the result set and include NextToken.

Example

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

import { DynamoDBClient, ExecuteStatementCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import
// const { DynamoDBClient, ExecuteStatementCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import
const client = new DynamoDBClient(config);
const input = { // ExecuteStatementInput
  Statement: "STRING_VALUE", // required
  Parameters: [ // PreparedStatementParameters
    { // AttributeValue Union: only one key present
      S: "STRING_VALUE",
      N: "STRING_VALUE",
      B: "BLOB_VALUE",
      SS: [ // StringSetAttributeValue
        "STRING_VALUE",
      ],
      NS: [ // NumberSetAttributeValue
        "STRING_VALUE",
      ],
      BS: [ // BinarySetAttributeValue
        "BLOB_VALUE",
      ],
      M: { // MapAttributeValue
        "<keys>": {//  Union: only one key present
          S: "STRING_VALUE",
          N: "STRING_VALUE",
          B: "BLOB_VALUE",
          SS: [
            "STRING_VALUE",
          ],
          NS: [
            "STRING_VALUE",
          ],
          BS: [
            "BLOB_VALUE",
          ],
          M: {
            "<keys>": "<AttributeValue>",
          },
          L: [ // ListAttributeValue
            "<AttributeValue>",
          ],
          NULL: true || false,
          BOOL: true || false,
        },
      },
      L: [
        "<AttributeValue>",
      ],
      NULL: true || false,
      BOOL: true || false,
    },
  ],
  ConsistentRead: true || false,
  NextToken: "STRING_VALUE",
  ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE",
  Limit: Number("int"),
};
const command = new ExecuteStatementCommand(input);
const response = await client.send(command);
// { // ExecuteStatementOutput
//   Items: [ // ItemList
//     { // AttributeMap
//       "<keys>": { // AttributeValue Union: only one key present
//         S: "STRING_VALUE",
//         N: "STRING_VALUE",
//         B: "BLOB_VALUE",
//         SS: [ // StringSetAttributeValue
//           "STRING_VALUE",
//         ],
//         NS: [ // NumberSetAttributeValue
//           "STRING_VALUE",
//         ],
//         BS: [ // BinarySetAttributeValue
//           "BLOB_VALUE",
//         ],
//         M: { // MapAttributeValue
//           "<keys>": {//  Union: only one key present
//             S: "STRING_VALUE",
//             N: "STRING_VALUE",
//             B: "BLOB_VALUE",
//             SS: [
//               "STRING_VALUE",
//             ],
//             NS: [
//               "STRING_VALUE",
//             ],
//             BS: [
//               "BLOB_VALUE",
//             ],
//             M: {
//               "<keys>": "<AttributeValue>",
//             },
//             L: [ // ListAttributeValue
//               "<AttributeValue>",
//             ],
//             NULL: true || false,
//             BOOL: true || false,
//           },
//         },
//         L: [
//           "<AttributeValue>",
//         ],
//         NULL: true || false,
//         BOOL: true || false,
//       },
//     },
//   ],
//   NextToken: "STRING_VALUE",
//   ConsumedCapacity: { // 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"),
//       },
//     },
//   },
//   LastEvaluatedKey: { // Key
//     "<keys>": "<AttributeValue>",
//   },
// };

Param

ExecuteStatementCommandInput

Returns

ExecuteStatementCommandOutput

See

• ExecuteStatementCommandInput for command's input shape.
• ExecuteStatementCommandOutput for command's response shape.
• config for DynamoDBClient's config shape.

Throws

ConditionalCheckFailedException (client fault)

A condition specified in the operation could not be evaluated.

Throws

DuplicateItemException (client fault)

There was an attempt to insert an item with the same primary key as an item that already exists in the DynamoDB table.

Throws

InternalServerError (server fault)

An error occurred on the server side.

Throws

ItemCollectionSizeLimitExceededException (client fault)

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

Throws

ProvisionedThroughputExceededException (client fault)

Your request rate is too high. The Amazon Web Services SDKs for DynamoDB automatically retry requests that receive this exception. Your request is eventually successful, unless your retry queue is too large to finish. Reduce the frequency of requests and use exponential backoff. For more information, go to Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide.

Throws

RequestLimitExceeded (client fault)

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

Throws

ResourceNotFoundException (client fault)

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

Throws

TransactionConflictException (client fault)

Operation was rejected because there is an ongoing transaction for the item.

Throws

DynamoDBServiceException

Base exception class for all service exceptions from DynamoDB service.