SDK for PHP 3.x

Amazon QLDB Session 2019-07-11

Client: Aws\QLDBSession\QLDBSessionClient
Service ID: qldb-session
Version: 2019-07-11

This page describes the parameters and results for the operations of the Amazon QLDB Session (2019-07-11), and shows how to use the Aws\QLDBSession\QLDBSessionClient object to call the described operations. This documentation is specific to the 2019-07-11 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

SendCommand ( array $params = [] )
Sends a command to an Amazon QLDB ledger.

Operations

SendCommand 

$result = $client->sendCommand([/* ... */]);
$promise = $client->sendCommandAsync([/* ... */]);

Sends a command to an Amazon QLDB ledger.

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

  • If you are working with an AWS SDK, use the QLDB driver. The driver provides a high-level abstraction layer above this QLDB Session data plane and manages SendCommand API calls 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 are 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.

Parameter Syntax

$result = $client->sendCommand([
    'AbortTransaction' => [
    ],
    'CommitTransaction' => [
        'CommitDigest' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED
        'TransactionId' => '<string>', // REQUIRED
    ],
    'EndSession' => [
    ],
    'ExecuteStatement' => [
        'Parameters' => [
            [
                'IonBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
                'IonText' => '<string>',
            ],
            // ...
        ],
        'Statement' => '<string>', // REQUIRED
        'TransactionId' => '<string>', // REQUIRED
    ],
    'FetchPage' => [
        'NextPageToken' => '<string>', // REQUIRED
        'TransactionId' => '<string>', // REQUIRED
    ],
    'SessionToken' => '<string>',
    'StartSession' => [
        'LedgerName' => '<string>', // REQUIRED
    ],
    'StartTransaction' => [
    ],
]);

Parameter Details

Members
AbortTransaction
Type: AbortTransactionRequest structure

Command to abort the current transaction.

CommitTransaction
Type: CommitTransactionRequest structure

Command to commit the specified transaction.

EndSession
Type: EndSessionRequest structure

Command to end the current session.

ExecuteStatement
Type: ExecuteStatementRequest structure

Command to execute a statement in the specified transaction.

FetchPage
Type: FetchPageRequest structure

Command to fetch a page.

SessionToken
Type: string

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.

StartSession
Type: StartSessionRequest structure

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

StartTransaction
Type: StartTransactionRequest structure

Command to start a new transaction.

Result Syntax

[
    'AbortTransaction' => [
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
    ],
    'CommitTransaction' => [
        'CommitDigest' => <string || resource || Psr\Http\Message\StreamInterface>,
        'ConsumedIOs' => [
            'ReadIOs' => <integer>,
            'WriteIOs' => <integer>,
        ],
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
        'TransactionId' => '<string>',
    ],
    'EndSession' => [
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
    ],
    'ExecuteStatement' => [
        'ConsumedIOs' => [
            'ReadIOs' => <integer>,
            'WriteIOs' => <integer>,
        ],
        'FirstPage' => [
            'NextPageToken' => '<string>',
            'Values' => [
                [
                    'IonBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
                    'IonText' => '<string>',
                ],
                // ...
            ],
        ],
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
    ],
    'FetchPage' => [
        'ConsumedIOs' => [
            'ReadIOs' => <integer>,
            'WriteIOs' => <integer>,
        ],
        'Page' => [
            'NextPageToken' => '<string>',
            'Values' => [
                [
                    'IonBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
                    'IonText' => '<string>',
                ],
                // ...
            ],
        ],
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
    ],
    'StartSession' => [
        'SessionToken' => '<string>',
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
    ],
    'StartTransaction' => [
        'TimingInformation' => [
            'ProcessingTimeMilliseconds' => <integer>,
        ],
        'TransactionId' => '<string>',
    ],
]

Result Details

Members
AbortTransaction
Type: AbortTransactionResult structure

Contains the details of the aborted transaction.

CommitTransaction
Type: CommitTransactionResult structure

Contains the details of the committed transaction.

EndSession
Type: EndSessionResult structure

Contains the details of the ended session.

ExecuteStatement
Type: ExecuteStatementResult structure

Contains the details of the executed statement.

FetchPage
Type: FetchPageResult structure

Contains the details of the fetched page.

StartSession
Type: StartSessionResult structure

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.

StartTransaction
Type: StartTransactionResult structure

Contains the details of the started transaction.

Errors

BadRequestException:

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

InvalidSessionException:

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

OccConflictException:

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

RateExceededException:

Returned when the rate of requests exceeds the allowed throughput.

LimitExceededException:

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

CapacityExceededException:

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

Shapes

AbortTransactionRequest

Description

Contains the details of the transaction to abort.

Members

AbortTransactionResult

Description

Contains the details of the aborted transaction.

Members
TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

BadRequestException

Description

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

Members
Code
Type: string
Message
Type: string

CapacityExceededException

Description

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

Members
Message
Type: string

CommitTransactionRequest

Description

Contains the details of the transaction to commit.

Members
CommitDigest
Required: Yes
Type: blob (string|resource|Psr\Http\Message\StreamInterface)

Specifies the commit digest for the transaction to commit. For every active transaction, the commit digest must be passed. QLDB validates CommitDigest and rejects the commit with an error if the digest computed on the client does not match the digest computed by QLDB.

The purpose of the CommitDigest parameter is to ensure that QLDB commits a transaction if and only if the server has processed the exact set of statements sent by the client, in the same order that client sent them, and with no duplicates.

TransactionId
Required: Yes
Type: string

Specifies the transaction ID of the transaction to commit.

CommitTransactionResult

Description

Contains the details of the committed transaction.

Members
CommitDigest
Type: blob (string|resource|Psr\Http\Message\StreamInterface)

The commit digest of the committed transaction.

ConsumedIOs
Type: IOUsage structure

Contains metrics about the number of I/O requests that were consumed.

TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

TransactionId
Type: string

The transaction ID of the committed transaction.

EndSessionRequest

Description

Specifies a request to end the session.

Members

EndSessionResult

Description

Contains the details of the ended session.

Members
TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

ExecuteStatementRequest

Description

Specifies a request to execute a statement.

Members
Parameters
Type: Array of ValueHolder structures

Specifies the parameters for the parameterized statement in the request.

Statement
Required: Yes
Type: string

Specifies the statement of the request.

TransactionId
Required: Yes
Type: string

Specifies the transaction ID of the request.

ExecuteStatementResult

Description

Contains the details of the executed statement.

Members
ConsumedIOs
Type: IOUsage structure

Contains metrics about the number of I/O requests that were consumed.

FirstPage
Type: Page structure

Contains the details of the first fetched page.

TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

FetchPageRequest

Description

Specifies the details of the page to be fetched.

Members
NextPageToken
Required: Yes
Type: string

Specifies the next page token of the page to be fetched.

TransactionId
Required: Yes
Type: string

Specifies the transaction ID of the page to be fetched.

FetchPageResult

Description

Contains the page that was fetched.

Members
ConsumedIOs
Type: IOUsage structure

Contains metrics about the number of I/O requests that were consumed.

Page
Type: Page structure

Contains details of the fetched page.

TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

IOUsage

Description

Contains I/O usage metrics for a command that was invoked.

Members
ReadIOs
Type: long (int|float)

The number of read I/O requests that the command made.

WriteIOs
Type: long (int|float)

The number of write I/O requests that the command made.

InvalidSessionException

Description

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

Members
Code
Type: string
Message
Type: string

LimitExceededException

Description

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

Members
Message
Type: string

OccConflictException

Description

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

Members
Message
Type: string

Page

Description

Contains details of the fetched page.

Members
NextPageToken
Type: string

The token of the next page.

Values
Type: Array of ValueHolder structures

A structure that contains values in multiple encoding formats.

RateExceededException

Description

Returned when the rate of requests exceeds the allowed throughput.

Members
Message
Type: string

StartSessionRequest

Description

Specifies a request to start a new session.

Members
LedgerName
Required: Yes
Type: string

The name of the ledger to start a new session against.

StartSessionResult

Description

Contains the details of the started session.

Members
SessionToken
Type: string

Session token of the started session. This SessionToken is required for every subsequent command that is issued during the current session.

TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

StartTransactionRequest

Description

Specifies a request to start a transaction.

Members

StartTransactionResult

Description

Contains the details of the started transaction.

Members
TimingInformation
Type: TimingInformation structure

Contains server-side performance information for the command.

TransactionId
Type: string

The transaction ID of the started transaction.

TimingInformation

Description

Contains server-side performance information for a command. Amazon QLDB captures timing information between the times when it receives the request and when it sends the corresponding response.

Members
ProcessingTimeMilliseconds
Type: long (int|float)

The amount of time that QLDB spent on processing the command, measured in milliseconds.

ValueHolder

Description

A structure that can contain a value in multiple encoding formats.

Members
IonBinary
Type: blob (string|resource|Psr\Http\Message\StreamInterface)

An Amazon Ion binary value contained in a ValueHolder structure.

IonText
Type: string

An Amazon Ion plaintext value contained in a ValueHolder structure.