SendCommand - Amazon Quantum Ledger Database (Amazon QLDB)

SendCommand

Sends a command to an Amazon QLDB ledger.

Note

Instead of interacting directly with this API, we recommend using the QLDB driver or the QLDB shell to run data transactions on a ledger.

  • If you're working with an AWS SDK, use the QLDB driver. The driver provides a high-level abstraction layer above this QLDB Session data API and manages the SendCommand operation for you. For information and a list of supported programming languages, see Getting started with the driver in the Amazon QLDB Developer Guide.

  • If you're working with the AWS Command Line Interface (AWS CLI), use the QLDB shell. The shell is a command line interface that uses the QLDB driver to interact with a ledger. For information, see Accessing Amazon QLDB using the QLDB shell.

Request Syntax

{ "AbortTransaction": { }, "CommitTransaction": { "CommitDigest": blob, "TransactionId": "string" }, "EndSession": { }, "ExecuteStatement": { "Parameters": [ { "IonBinary": blob, "IonText": "string" } ], "Statement": "string", "TransactionId": "string" }, "FetchPage": { "NextPageToken": "string", "TransactionId": "string" }, "SessionToken": "string", "StartSession": { "LedgerName": "string" }, "StartTransaction": { } }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

AbortTransaction

Command to abort the current transaction.

Type: AbortTransactionRequest object

Required: No

CommitTransaction

Command to commit the specified transaction.

Type: CommitTransactionRequest object

Required: No

EndSession

Command to end the current session.

Type: EndSessionRequest object

Required: No

ExecuteStatement

Command to execute a statement in the specified transaction.

Type: ExecuteStatementRequest object

Required: No

FetchPage

Command to fetch a page.

Type: FetchPageRequest object

Required: No

SessionToken

Specifies the session token for the current command. A session token is constant throughout the life of the session.

To obtain a session token, run the StartSession command. This SessionToken is required for every subsequent command that is issued during the current session.

Type: String

Length Constraints: Minimum length of 4. Maximum length of 1024.

Pattern: ^[A-Za-z-0-9+/=]+$

Required: No

StartSession

Command to start a new session. A session token is obtained as part of the response.

Type: StartSessionRequest object

Required: No

StartTransaction

Command to start a new transaction.

Type: StartTransactionRequest object

Required: No

Response Syntax

{ "AbortTransaction": { "TimingInformation": { "ProcessingTimeMilliseconds": number } }, "CommitTransaction": { "CommitDigest": blob, "ConsumedIOs": { "ReadIOs": number, "WriteIOs": number }, "TimingInformation": { "ProcessingTimeMilliseconds": number }, "TransactionId": "string" }, "EndSession": { "TimingInformation": { "ProcessingTimeMilliseconds": number } }, "ExecuteStatement": { "ConsumedIOs": { "ReadIOs": number, "WriteIOs": number }, "FirstPage": { "NextPageToken": "string", "Values": [ { "IonBinary": blob, "IonText": "string" } ] }, "TimingInformation": { "ProcessingTimeMilliseconds": number } }, "FetchPage": { "ConsumedIOs": { "ReadIOs": number, "WriteIOs": number }, "Page": { "NextPageToken": "string", "Values": [ { "IonBinary": blob, "IonText": "string" } ] }, "TimingInformation": { "ProcessingTimeMilliseconds": number } }, "StartSession": { "SessionToken": "string", "TimingInformation": { "ProcessingTimeMilliseconds": number } }, "StartTransaction": { "TimingInformation": { "ProcessingTimeMilliseconds": number }, "TransactionId": "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.

AbortTransaction

Contains the details of the aborted transaction.

Type: AbortTransactionResult object

CommitTransaction

Contains the details of the committed transaction.

Type: CommitTransactionResult object

EndSession

Contains the details of the ended session.

Type: EndSessionResult object

ExecuteStatement

Contains the details of the executed statement.

Type: ExecuteStatementResult object

FetchPage

Contains the details of the fetched page.

Type: FetchPageResult object

StartSession

Contains the details of the started session that includes a session token. This SessionToken is required for every subsequent command that is issued during the current session.

Type: StartSessionResult object

StartTransaction

Contains the details of the started transaction.

Type: StartTransactionResult object

Errors

For information about the errors that are common to all actions, see Common Errors.

BadRequestException

Returned if the request is malformed or contains an error such as an invalid parameter value or a missing required parameter.

HTTP Status Code: 400

CapacityExceededException

Returned when the request exceeds the processing capacity of the ledger.

HTTP Status Code: 400

InvalidSessionException

Returned if the session doesn't exist anymore because it timed out or expired.

HTTP Status Code: 400

LimitExceededException

Returned if a resource limit such as number of active sessions is exceeded.

HTTP Status Code: 400

OccConflictException

Returned when a transaction cannot be written to the journal due to a failure in the verification phase of optimistic concurrency control (OCC).

HTTP Status Code: 400

RateExceededException

Returned when the rate of requests exceeds the allowed throughput.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: