ExecuteStatement
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.
Request Syntax
POST /Execute HTTP/1.1
Content-type: application/json
{
"continueAfterTimeout": boolean
,
"database": "string
",
"formatRecordsAs": "string
",
"includeResultMetadata": boolean
,
"parameters": [
{
"name": "string
",
"typeHint": "string
",
"value": {
"arrayValue": {
"arrayValues": [
"ArrayValue"
],
"booleanValues": [ boolean
],
"doubleValues": [ number
],
"longValues": [ number
],
"stringValues": [ "string
" ]
},
"blobValue": blob
,
"booleanValue": boolean
,
"doubleValue": number
,
"isNull": boolean
,
"longValue": number
,
"stringValue": "string
"
}
}
],
"resourceArn": "string
",
"resultSetOptions": {
"decimalReturnType": "string
",
"longReturnType": "string
"
},
"schema": "string
",
"secretArn": "string
",
"sql": "string
",
"transactionId": "string
"
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- continueAfterTimeout
-
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.
Note 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.
Type: Boolean
Required: No
- database
-
The name of the database.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No
- formatRecordsAs
-
A value that indicates whether to format the result set as a single JSON string. This parameter only applies to
SELECT
statements and is ignored for other types of statements. Allowed values areNONE
andJSON
. The default value isNONE
. The result is returned in theformattedRecords
field.For usage information about the JSON format for result sets, see Using the Data API in the Amazon Aurora User Guide.
Type: String
Valid Values:
NONE | JSON
Required: No
- includeResultMetadata
-
A value that indicates whether to include metadata in the results.
Type: Boolean
Required: No
- parameters
-
The parameters for the SQL statement.
Note Array parameters are not supported.
Type: Array of SqlParameter objects
Required: No
- resourceArn
-
The Amazon Resource Name (ARN) of the Aurora Serverless DB cluster.
Type: String
Length Constraints: Minimum length of 11. Maximum length of 100.
Required: Yes
- resultSetOptions
-
Options that control how the result set is returned.
Type: ResultSetOptions object
Required: No
- schema
-
The name of the database schema.
Note Currently, the
schema
parameter isn't supported.Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No
- secretArn
-
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.
Type: String
Length Constraints: Minimum length of 11. Maximum length of 100.
Required: Yes
- sql
-
The SQL statement to run.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 65536.
Required: Yes
- transactionId
-
The identifier of a transaction that was started by using the
BeginTransaction
operation. Specify the transaction ID of the transaction that you want to include the SQL statement in.If the SQL statement is not part of a transaction, don't set this parameter.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 192.
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"columnMetadata": [
{
"arrayBaseColumnType": number,
"isAutoIncrement": boolean,
"isCaseSensitive": boolean,
"isCurrency": boolean,
"isSigned": boolean,
"label": "string",
"name": "string",
"nullable": number,
"precision": number,
"scale": number,
"schemaName": "string",
"tableName": "string",
"type": number,
"typeName": "string"
}
],
"formattedRecords": "string",
"generatedFields": [
{
"arrayValue": {
"arrayValues": [
"ArrayValue"
],
"booleanValues": [ boolean ],
"doubleValues": [ number ],
"longValues": [ number ],
"stringValues": [ "string" ]
},
"blobValue": blob,
"booleanValue": boolean,
"doubleValue": number,
"isNull": boolean,
"longValue": number,
"stringValue": "string"
}
],
"numberOfRecordsUpdated": number,
"records": [
[
{
"arrayValue": {
"arrayValues": [
"ArrayValue"
],
"booleanValues": [ boolean ],
"doubleValues": [ number ],
"longValues": [ number ],
"stringValues": [ "string" ]
},
"blobValue": blob,
"booleanValue": boolean,
"doubleValue": number,
"isNull": boolean,
"longValue": number,
"stringValue": "string"
}
]
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- columnMetadata
-
Metadata for the columns included in the results. This field is blank if the
formatRecordsAs
parameter is set toJSON
.Type: Array of ColumnMetadata objects
- formattedRecords
-
A string value that represents the result set of a
SELECT
statement in JSON format. This value is only present when theformatRecordsAs
parameter is set toJSON
.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.
Type: String
- generatedFields
-
Values for fields generated during a DML request.
Note The
generatedFields
data isn't supported by Aurora PostgreSQL. To get the values of generated fields, use theRETURNING
clause. For more information, see Returning Data From Modified Rowsin the PostgreSQL documentation. Type: Array of Field objects
- numberOfRecordsUpdated
-
The number of records updated by the request.
Type: Long
- records
-
The records returned by the SQL statement. This field is blank if the
formatRecordsAs
parameter is set toJSON
.Type: Array of arrays of Field objects
Errors
- AccessDeniedException
-
You do not have sufficient access to perform this action.
HTTP Status Code: 403
- BadRequestException
-
There is an error in the call or in a SQL statement.
HTTP Status Code: 400
- ForbiddenException
-
There are insufficient privileges to make the call.
HTTP Status Code: 403
- InternalServerErrorException
-
An internal error occurred.
HTTP Status Code: 500
- ServiceUnavailableError
-
The service specified by the
resourceArn
parameter is not available.HTTP Status Code: 503
- StatementTimeoutException
-
The execution of the SQL statement timed out.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: