Transaction APIs - AWS Lake Formation

Transaction APIs

The Transaction APIs describes operations for transactionally updating the contents of a table in AWS Lake Formation.

Data Types

TransactionDescription Structure

A structure that contains information about a transaction.

Fields

  • TransactionId – UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The ID of the transaction.

  • TransactionStatus – UTF-8 string (valid values: ACTIVE | COMMITTED | ABORTED | COMMIT_IN_PROGRESS).

    A status of ACTIVE, COMMITTED, or ABORTED.

  • TransactionStartTime – Timestamp.

    The time when the transaction started.

  • TransactionEndTime – Timestamp.

    The time when the transaction committed or aborted, if it is not currently active.

VirtualObject Structure

An object that defines an Amazon S3 object to be deleted if a transaction cancels, provided that VirtualPut was called before writing the object.

Fields

  • UriRequired: Uniform resource identifier (uri), not less than 1 or more than 1024 bytes long, matching the URI address multi-line string pattern.

    The path to the Amazon S3 object. Must start with s3://

  • ETag – UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The ETag of the Amazon S3 object.

Operations

StartTransaction Action (Python: start_transaction)

Starts a new transaction and returns its transaction ID. Transaction IDs are opaque objects that you can use to identify a transaction.

Request

  • TransactionType – UTF-8 string (valid values: READ_AND_WRITE | READ_ONLY).

    Indicates whether this transaction should be read only or read and write. Writes made using a read-only transaction ID will be rejected. Read-only transactions do not need to be committed.

Response

  • TransactionId – UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    An opaque identifier for the transaction.

Errors

  • InternalServiceException

  • OperationTimeoutException

CommitTransaction Action (Python: commit_transaction)

Attempts to commit the specified transaction. Returns an exception if the transaction was previously aborted. This API action is idempotent if called multiple times for the same transaction.

Request

  • TransactionIdRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The transaction to commit.

Response

  • TransactionStatus – UTF-8 string (valid values: ACTIVE | COMMITTED | ABORTED | COMMIT_IN_PROGRESS).

    The status of the transaction.

Errors

  • InvalidInputException

  • EntityNotFoundException

  • InternalServiceException

  • OperationTimeoutException

  • TransactionCanceledException

  • ConcurrentModificationException

CancelTransaction Action (Python: cancel_transaction)

Attempts to cancel the specified transaction. Returns an exception if the transaction was previously committed.

Request

  • TransactionIdRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The transaction to cancel.

Response

  • No Response parameters.

Errors

  • InvalidInputException

  • EntityNotFoundException

  • InternalServiceException

  • OperationTimeoutException

  • TransactionCommittedException

  • TransactionCommitInProgressException

  • ConcurrentModificationException

ExtendTransaction Action (Python: extend_transaction)

Indicates to the service that the specified transaction is still active and should not be treated as idle and aborted.

Write transactions that remain idle for a long period are automatically aborted unless explicitly extended.

Request

  • TransactionId – UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The transaction to extend.

Response

  • No Response parameters.

Errors

  • InvalidInputException

  • EntityNotFoundException

  • InternalServiceException

  • OperationTimeoutException

  • TransactionCommittedException

  • TransactionCanceledException

  • TransactionCommitInProgressException

DescribeTransaction Action (Python: describe_transaction)

Returns the details of a single transaction.

Request

  • TransactionIdRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    The transaction for which to return status.

Response

  • TransactionDescription – A TransactionDescription object.

    Returns a TransactionDescription object containing information about the transaction.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

ListTransactions Action (Python: list_transactions)

Returns metadata about transactions and their status. To prevent the response from growing indefinitely, only uncommitted transactions and those available for time-travel queries are returned.

This operation can help you identify uncommitted transactions or to get information about transactions.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The catalog for which to list transactions. Defaults to the account ID of the caller.

  • StatusFilter – UTF-8 string (valid values: ALL | COMPLETED | ACTIVE | COMMITTED | ABORTED).

    A filter indicating the status of transactions to return. Options are ALL | COMPLETED | COMMITTED | ABORTED | ACTIVE. The default is ALL.

  • MaxResults – Number (integer), not less than 1 or more than 1000.

    The maximum number of transactions to return in a single call.

  • NextToken – UTF-8 string, not more than 4096 bytes long.

    A continuation token if this is not the first call to retrieve transactions.

Response

  • Transactions – An array of TransactionDescription objects.

    A list of transactions. The record for each transaction is a TransactionDescription object.

  • NextToken – UTF-8 string, not more than 4096 bytes long.

    A continuation token indicating whether additional data is available.

Errors

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

DeleteObjectsOnCancel Action (Python: delete_objects_on_cancel)

For a specific governed table, provides a list of Amazon S3 objects that will be written during the current transaction and that can be automatically deleted if the transaction is canceled. Without this call, no Amazon S3 objects are automatically deleted when a transaction cancels.

The AWS Glue ETL library function write_dynamic_frame.from_catalog() includes an option to automatically call DeleteObjectsOnCancel before writes. For more information, see Rolling Back Amazon S3 Writes.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The AWS Glue data catalog that contains the governed table. Defaults to the current account ID.

  • DatabaseNameRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The database that contains the governed table.

  • TableNameRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The name of the governed table.

  • TransactionIdRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Custom string pattern #11.

    ID of the transaction that the writes occur in.

  • ObjectsRequired: An array of VirtualObject objects, not less than 1 or more than 100 structures.

    A list of VirtualObject structures, which indicates the Amazon S3 objects to be deleted if the transaction cancels.

Response

  • No Response parameters.

Errors

  • InternalServiceException

  • InvalidInputException

  • OperationTimeoutException

  • EntityNotFoundException

  • TransactionCommittedException

  • TransactionCanceledException

  • ResourceNotReadyException

  • ConcurrentModificationException

Exceptions

TransactionCommitInProgressException Structure

Contains details about an error related to a transaction commit that was in progress.

Fields

  • Message – UTF-8 string.

    A message describing the error.

TransactionAbortedException Structure

Contains details about an error where the specified transaction has already been aborted and cannot be used for UpdateTableObjects.

Fields

  • Message – UTF-8 string.

    A message describing the error.

TransactionCommittedException Structure

Contains details about an error where the specified transaction has already been committed and cannot be used for UpdateTableObjects.

Fields

  • Message – UTF-8 string.

    A message describing the error.

TransactionCanceledException Structure

Contains details about an error related to a transaction that was cancelled.

Fields

  • Message – UTF-8 string.

    A message describing the error.

TransactionContentionException Structure

Contains details about a retryable error indicating that the commit did not succeed due to a contention or conflict.

Fields

  • Message – UTF-8 string.

    A message describing the error.

ResourceNotReadyException Structure

Contains details about an error related to a resource which is not ready for a transaction.

Fields

  • Message – UTF-8 string.

    A message describing the error.