REDACT_REVISION stored procedure in Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)
Redaction considerations and limitationsSyntaxArgumentsReturn valueExamples

REDACT_REVISION stored procedure in Amazon QLDB

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

Note

Any ledgers that were created before July 22, 2021 are currently not eligible for redaction. You can view the creation time of your ledger on the Amazon QLDB console.

In Amazon QLDB, use the REDACT_REVISION stored procedure to permanently delete an individual, inactive document revision in both indexed storage and journal storage. This stored procedure deletes all of the user data in the specified revision. However, it leaves the journal sequence and the document metadata, including the document ID and hash, unchanged. This operation is irreversible.

The specified document revision must be an inactive revision in history. The latest active revision of a document is not eligible for redaction.

After you submit a redaction request by running this stored procedure, QLDB processes the redaction of data asynchronously. After a redaction is complete, the user data of the specified revision (represented by the data structure) is replaced by a new dataHash field. The value of this field is the Amazon Ion hash of the removed data structure. As a result, the ledger maintains its overall data integrity and remains cryptographically verifiable through the existing verification API operations.

For an example of a redaction operation with sample data, see Redaction example in Redacting document revisions.

Note

To learn how to control access to run this PartiQL command on specific tables, see Getting started with the standard permissions mode in Amazon QLDB.

Redaction considerations and limitations

Before you get started with data redaction in Amazon QLDB, make sure that you review the following considerations and limitations:

  • The REDACT_REVISION stored procedure targets your user data in an individual, inactive document revision. To redact multiple revisions, you must run the stored procedure once for each revision. You can redact one revision per transaction.

  • To redact particular fields within a document revision, you must use a separate data manipulation language (DML) statement to modify the revision first. For more information, see Redacting a particular field within a revision.

  • After QLDB receives a redaction request, you can't cancel or alter the request. To confirm whether a redaction is complete, you can check if the data structure of a revision has been replaced by a dataHash field. To learn more, see Checking whether a redaction is complete.

  • Redaction has no impact on any QLDB data that is replicated outside of the QLDB service. This includes any exports to Amazon S3 and streams to Amazon Kinesis Data Streams. You must use other data retention methods to manage any data stored outside of QLDB.

  • Redaction has no impact on literal values in PartiQL statements that are recorded in the journal. As a best practice, you should run parameterized statements programmatically by using variable placeholders instead of literal values. A placeholder is written in the journal as a question mark (?) instead of any sensitive information that might require redaction.

    To learn how to programmatically run PartiQL statements using the QLDB driver, see the tutorials for each supported programming language in Getting started with the driver.

Syntax

EXEC REDACT_REVISION `block-address`, 'table-id', 'document-id'

Arguments

`block-address`

The journal block location of the document revision to be redacted. An address is an Amazon Ion structure that has two fields: strandId and sequenceNo.

This is an Ion literal value that is denoted by backticks. For example:

`{strandId:"JdxjkR9bSYB5jMHWcI464T", sequenceNo:17}`

To learn how to find the block address, see Querying document metadata.

'table-id'

The unique ID of the table whose document revision you want to redact, denoted by single quotation marks.

To learn how to find the table ID, see Querying the system catalog.

'document-id'

The unique document ID of the revision to be redacted, denoted by single quotation marks.

To learn how to find the document ID, see Querying document metadata.

Return value

An Amazon Ion structure that represents the document revision to be redacted, in the following format.

{
  blockAddress: {
    strandId: String,
    sequenceNo: Int
  },
  tableId: String,
  documentId: String,
  version: Int
}
Return structure fields

  • blockAddress – The journal block location of the revision to be redacted. An address has the following two fields.

    • strandId – The unique ID of the journal strand that contains the block.

    • sequenceNo – An index number that specifies the location of the block within the strand.

  • tableId – The unique ID of the table whose revision you are redacting.

  • documentId – The unique document ID of the revision to be redacted.

  • version – The version number of the document revision to be redacted.

The following is an example of the return structure with sample data.

{
  blockAddress: {
    strandId: "CsRnx0RDoNK6ANEEePa1ov",
    sequenceNo: 134
  },
  tableId: "6GZumdHggklLdMGyQq9DNX",
  documentId: "IXlQPSbfyKMIIsygePeKrZ",
  version: 0
}

Examples

EXEC REDACT_REVISION `{strandId:"7z2P0AyQKWD8oFYmGNhi8D", sequenceNo:7}`, '8F0TPCmdNQ6JTRpiLj2TmW', '05K8zpGYWynDlEOK5afDRc'