- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
ExecuteStatementCommand
Runs a SQL statement against a database.
If a call isn't part of a transaction because it doesn't include the transactionID
parameter, changes that result from the call are committed automatically.
If the binary response data from the database is more than 1 MB, the call is terminated.
Example Syntax
Use a bare-bones client and the command you need to make an API call.
import { RDSDataClient, ExecuteStatementCommand } from "@aws-sdk/client-rds-data"; // ES Modules import
// const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data"); // CommonJS import
const client = new RDSDataClient(config);
const input = { // ExecuteStatementRequest
resourceArn: "STRING_VALUE", // required
secretArn: "STRING_VALUE", // required
sql: "STRING_VALUE", // required
database: "STRING_VALUE",
schema: "STRING_VALUE",
parameters: [ // SqlParametersList
{ // SqlParameter
name: "STRING_VALUE",
value: { // Field Union: only one key present
isNull: true || false,
booleanValue: true || false,
longValue: Number("long"),
doubleValue: Number("double"),
stringValue: "STRING_VALUE",
blobValue: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
arrayValue: { // ArrayValue Union: only one key present
booleanValues: [ // BooleanArray
true || false,
],
longValues: [ // LongArray
Number("long"),
],
doubleValues: [ // DoubleArray
Number("double"),
],
stringValues: [ // StringArray
"STRING_VALUE",
],
arrayValues: [ // ArrayOfArray
{// Union: only one key present
booleanValues: [
true || false,
],
longValues: [
Number("long"),
],
doubleValues: [
Number("double"),
],
stringValues: [
"STRING_VALUE",
],
arrayValues: [
"<ArrayValue>",
],
},
],
},
},
typeHint: "STRING_VALUE",
},
],
transactionId: "STRING_VALUE",
includeResultMetadata: true || false,
continueAfterTimeout: true || false,
resultSetOptions: { // ResultSetOptions
decimalReturnType: "STRING_VALUE",
longReturnType: "STRING_VALUE",
},
formatRecordsAs: "STRING_VALUE",
};
const command = new ExecuteStatementCommand(input);
const response = await client.send(command);
// { // ExecuteStatementResponse
// records: [ // SqlRecords
// [ // FieldList
// { // Field Union: only one key present
// isNull: true || false,
// booleanValue: true || false,
// longValue: Number("long"),
// doubleValue: Number("double"),
// stringValue: "STRING_VALUE",
// blobValue: new Uint8Array(),
// arrayValue: { // ArrayValue Union: only one key present
// booleanValues: [ // BooleanArray
// true || false,
// ],
// longValues: [ // LongArray
// Number("long"),
// ],
// doubleValues: [ // DoubleArray
// Number("double"),
// ],
// stringValues: [ // StringArray
// "STRING_VALUE",
// ],
// arrayValues: [ // ArrayOfArray
// {// Union: only one key present
// booleanValues: [
// true || false,
// ],
// longValues: [
// Number("long"),
// ],
// doubleValues: [
// Number("double"),
// ],
// stringValues: [
// "STRING_VALUE",
// ],
// arrayValues: [
// "<ArrayValue>",
// ],
// },
// ],
// },
// },
// ],
// ],
// columnMetadata: [ // Metadata
// { // ColumnMetadata
// name: "STRING_VALUE",
// type: Number("int"),
// typeName: "STRING_VALUE",
// label: "STRING_VALUE",
// schemaName: "STRING_VALUE",
// tableName: "STRING_VALUE",
// isAutoIncrement: true || false,
// isSigned: true || false,
// isCurrency: true || false,
// isCaseSensitive: true || false,
// nullable: Number("int"),
// precision: Number("int"),
// scale: Number("int"),
// arrayBaseColumnType: Number("int"),
// },
// ],
// numberOfRecordsUpdated: Number("long"),
// generatedFields: [
// {// Union: only one key present
// isNull: true || false,
// booleanValue: true || false,
// longValue: Number("long"),
// doubleValue: Number("double"),
// stringValue: "STRING_VALUE",
// blobValue: new Uint8Array(),
// arrayValue: "<ArrayValue>",
// },
// ],
// formattedRecords: "STRING_VALUE",
// };
ExecuteStatementCommand Input
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
resourceArn Required | string | undefined | The Amazon Resource Name (ARN) of the Aurora Serverless DB cluster. |
secretArn Required | string | undefined | The ARN of the secret that enables access to the DB cluster. Enter the database user name and password for the credentials in the secret. For information about creating the secret, see Create a database secret . |
sql Required | string | undefined | The SQL statement to run. |
continueAfterTimeout | boolean | undefined | A value that indicates whether to continue running the statement after the call times out. By default, the statement stops running when the call times out. For DDL statements, we recommend continuing to run the statement after the call times out. When a DDL statement terminates before it is finished running, it can result in errors and possibly corrupted data structures. |
database | string | undefined | The name of the database. |
formatRecordsAs | RecordsFormatType | undefined | A value that indicates whether to format the result set as a single JSON string. This parameter only applies to For usage information about the JSON format for result sets, see Using the Data API in the Amazon Aurora User Guide. |
includeResultMetadata | boolean | undefined | A value that indicates whether to include metadata in the results. |
parameters | SqlParameter[] | undefined | The parameters for the SQL statement. Array parameters are not supported. |
resultSetOptions | ResultSetOptions | undefined | Options that control how the result set is returned. |
schema | string | undefined | The name of the database schema. Currently, the |
transactionId | string | undefined | The identifier of a transaction that was started by using the If the SQL statement is not part of a transaction, don't set this parameter. |
ExecuteStatementCommand Output
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
$metadata Required | ResponseMetadata | Metadata pertaining to this request. |
columnMetadata | ColumnMetadata[] | undefined | Metadata for the columns included in the results. This field is blank if the |
formattedRecords | string | undefined | A string value that represents the result set of a The size limit for this field is currently 10 MB. If the JSON-formatted string representing the result set requires more than 10 MB, the call returns an error. |
generatedFields | Field[] | undefined | Values for fields generated during a DML request. The |
numberOfRecordsUpdated | number | undefined | The number of records updated by the request. |
records | Field[][] | undefined | The records returned by the SQL statement. This field is blank if the |
Throws
Name | Fault | Details |
---|
Name | Fault | Details |
---|---|---|
AccessDeniedException | client | You don't have sufficient access to perform this action. |
BadRequestException | client | There is an error in the call or in a SQL statement. (This error only appears in calls from Aurora Serverless v1 databases.) |
DatabaseErrorException | client | There was an error in processing the SQL statement. |
DatabaseNotFoundException | client | The DB cluster doesn't have a DB instance. |
DatabaseResumingException | client | A request was cancelled because the Aurora Serverless v2 DB instance was paused. The Data API request automatically resumes the DB instance. Wait a few seconds and try again. |
DatabaseUnavailableException | server | The writer instance in the DB cluster isn't available. |
ForbiddenException | client | There are insufficient privileges to make the call. |
HttpEndpointNotEnabledException | client | The HTTP endpoint for using RDS Data API isn't enabled for the DB cluster. |
InternalServerErrorException | server | An internal error occurred. |
InvalidResourceStateException | client | The resource is in an invalid state. |
InvalidSecretException | client | The Secrets Manager secret used with the request isn't valid. |
SecretsErrorException | client | There was a problem with the Secrets Manager secret used with the request, caused by one of the following conditions:
|
ServiceUnavailableError | server | The service specified by the |
StatementTimeoutException | client | The execution of the SQL statement timed out. |
TransactionNotFoundException | client | The transaction ID wasn't found. |
UnsupportedResultException | client | There was a problem with the result because of one of the following conditions:
|
RDSDataServiceException | Base exception class for all service exceptions from RDSData service. |