Amazon RDS Data Service
API Reference (API Version 2018-08-01)

ExecuteStatement

Runs a SQL statement against a database.

Important

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.

The response size limit is 1 MB or 1,000 records. If the call returns more than 1 MB of response data or over 1,000 records, the call is terminated.

Request Syntax

POST /Execute HTTP/1.1 Content-type: application/json { "continueAfterTimeout": boolean, "database": "string", "includeResultMetadata": boolean, "parameters": [ { "name": "string", "typeHint": "string", "value": { "arrayValue": { "arrayValues": [ "ArrayValue" ], "blobValues": [ blob ], "booleanValues": [ boolean ], "doubleValues": [ number ], "longValues": [ number ], "stringValues": [ "string" ] }, "blobValue": blob, "booleanValue": boolean, "doubleValue": number, "isNull": boolean, "longValue": number, "stringValue": "string", "structValue": { "string" : "Field" } } } ], "resourceArn": "string", "resultSetOptions": { "decimalReturnType": "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.

Important

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

includeResultMetadata

A value that indicates whether to include metadata in the results.

Type: Boolean

Required: No

parameters

The parameters for the SQL statement.

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.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 64.

Required: No

secretArn

The name or ARN of the secret that enables access to the DB cluster.

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" } ], "generatedFields": [ { "arrayValue": { "arrayValues": [ "ArrayValue" ], "blobValues": [ blob ], "booleanValues": [ boolean ], "doubleValues": [ number ], "longValues": [ number ], "stringValues": [ "string" ] }, "blobValue": blob, "booleanValue": boolean, "doubleValue": number, "isNull": boolean, "longValue": number, "stringValue": "string", "structValue": { "string" : "Field" } } ], "numberOfRecordsUpdated": number, "records": [ [ { "arrayValue": { "arrayValues": [ "ArrayValue" ], "blobValues": [ blob ], "booleanValues": [ boolean ], "doubleValues": [ number ], "longValues": [ number ], "stringValues": [ "string" ] }, "blobValue": blob, "booleanValue": boolean, "doubleValue": number, "isNull": boolean, "longValue": number, "stringValue": "string", "structValue": { "string" : "Field" } } ] ] }

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.

Type: Array of ColumnMetadata objects

generatedFields

Values for fields generated during the request.

Note

The generatedFields data isn't supported by Aurora PostgreSQL. To get the values of generated fields, use the RETURNING clause. For more information, see Returning Data From Modified Rows in 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.

Type: Array of arrays of Field objects

Errors

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: