Updating and deleting documents

In Amazon QLDB, a document revision is an Amazon Ion structure that represents a single version of a sequence of documents that are identified by a unique document ID. Every revision contains the document's full dataset, including both your user data and system-generated metadata. Each revision is uniquely identified by a combination of the document ID and a zero-based version number.

When you update a document, QLDB creates a new revision with the same document ID and an incremented version number. The lifecycle of a document ends when you delete it from a table. This means that no document revision with the same document ID can be created again.

Making document revisions

For example, the following statements insert a new vehicle registration, update the registration city, and then delete the registration. This results in three revisions of a document.

INSERT INTO VehicleRegistration
{
    'VIN' : '1HVBBAANXWH544237',
    'LicensePlateNumber' : 'LS477D',
    'State' : 'WA',
    'City' : 'Tacoma',
    'PendingPenaltyTicketAmount' : 42.20,
    'ValidFromDate' : `2011-10-26T`,
    'ValidToDate' : `2023-09-25T`,
    'Owners' : {
        'PrimaryOwner' : { 'PersonId': 'KmA3XPKKFqYCP2zhR3d0Ho' },
        'SecondaryOwners' : []
    }
}

Note

Insert statements and other DML statements return the ID of each affected document. Before you continue, save this ID because you need it for the history function in the next topic. You can also find the document ID with the following query.

SELECT r_id FROM VehicleRegistration AS r BY r_id
WHERE r.VIN = '1HVBBAANXWH544237'

UPDATE VehicleRegistration AS r 
SET r.City = 'Bellevue' 
WHERE r.VIN = '1HVBBAANXWH544237'

DELETE FROM VehicleRegistration AS r 
WHERE r.VIN = '1HVBBAANXWH544237'

For more examples and information about the syntax of these DML statements, see UPDATE and DELETE in the Amazon QLDB PartiQL reference.

To insert and remove specific elements within a document, you can use UPDATE statements or other DML statements that start with the FROM keyword. For information and examples, see the FROM (INSERT, REMOVE, or SET) reference.

After you delete a document, you can no longer query it in the committed or user views. To learn how to query the revision history of this document using the built-in history function, proceed to Querying revision history.