Step 5: View the revision history for a document

After modifying registration data for the car with VIN 1N4AL11D75C109151, you can query the history of all its registered owners and any other updated fields. You can see all revisions of a document that you inserted, updated, and deleted by querying the built-in History function.

The history function returns revisions from the committed view of your table, which includes both your application data and the associated metadata. The metadata shows exactly when each revision was made, in what order, and which transaction committed them.

In this step, you query the revision history of a document in the VehicleRegistration table in the vehicle-registration ledger.

To view the revision history

1. Open the Amazon QLDB console at https://console.aws.amazon.com/qldb.

2. In the navigation pane, choose PartiQL editor.

3. Choose the vehicle-registration ledger.

4. To query the history of a document, start by finding its unique id. In addition to querying the committed view, another way of getting a document id is to use the BY keyword in the table's default user view. To learn more, see Using the BY clause to query document ID.

   In the query editor window, enter the following statement, and then choose Run.

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

5. Next, you can use this id value to query the history function. Enter the following statement, and then choose Run. Be sure to replace the id value with your own document ID as appropriate.

   SELECT h.data.VIN, h.data.City, h.data.Owners
   FROM history(VehicleRegistration) AS h
   WHERE h.metadata.id = 'ADR2LQq48kB9neZDupQrMm' --replace with your id

   Note

   For the purposes of this tutorial, this history query returns all revisions of document ID ADR2LQq48kB9neZDupQrMm. As a best practice, however, qualify a history query with both a document ID and a date range (start time and end time).

   In QLDB, every SELECT query is processed in a transaction and is subject to a transaction timeout limit. History queries that include a start time and end time gain the benefit of date range qualification. For more information, see History function.

   The history function returns documents in the same schema as the committed view. This example projects your modified vehicle registration data. The output should look similar to the following.

   VIN	City	Owners
   "1N4AL11D75C109151"	"Seattle"	{PrimaryOwner:{PersonId:""},SecondaryOwners:[]}
   "1N4AL11D75C109151"	"Seattle"	{PrimaryOwner:{PersonId:"294jJ3YUoH1IEEm8GSabOs"}, SecondaryOwners:[]}
   "1N4AL11D75C109151"	"Everett"	{PrimaryOwner:{PersonId:"7NmE8YLPbXc0IqesJy1rpR"}, SecondaryOwners:[]}
   "1N4AL11D75C109151"	"Everett"	{PrimaryOwner:{PersonId:"7NmE8YLPbXc0IqesJy1rpR"}, SecondaryOwners:[{PersonId:"5Ufgdlnj06gF5CWcOIu64s"}]}

   Note

   The history query might not always return document revisions in sequential order.

   Review the output and confirm that the changes reflect what you did in Step 4: Modify documents in a ledger.

6. Then, you can inspect the document metadata of each revision. Enter the following statement, and then choose Run. Again, be sure to replace the id value with your own document ID as appropriate.

   SELECT VALUE h.metadata
   FROM history(VehicleRegistration) AS h
   WHERE h.metadata.id = 'ADR2LQq48kB9neZDupQrMm' --replace with your id

   The output should look similar to the following.

   version	id	txTime	txId
   0	"ADR2LQq48kB9neZDupQrMm"	2019-05-23T19:20:360d-3Z	"FMoVdWuPxJg3k466Iz4i75"
   1	"ADR2LQq48kB9neZDupQrMm"	2019-05-23T21:40:199d-3Z	"KWByxe842Xw8DNHcvARPOt"
   2	"ADR2LQq48kB9neZDupQrMm"	2019-05-23T21:44:432d-3Z	"EKwDOJRwbHpFvmAyJ2Kdh9"
   3	"ADR2LQq48kB9neZDupQrMm"	2019-05-23T21:49:254d-3Z	"96EiZd7vCmJ6RAvOvTZ4YA"

   These metadata fields provide details on when each item was modified, and by which transaction. From this data, you can infer the following:

   • The document is uniquely identified by its system-assigned id: ADR2LQq48kB9neZDupQrMm. This is a universally unique identifier (UUID) that is represented in a Base62-encoded string.

   • The txTime shows that the initial revision of the document (version 0) was created at 2019-05-23T19:20:360d-3Z.

   • Each subsequent transaction creates a new revision with the same document id, an incremented version number, and an updated txId and txTime.

To verify a document revision cryptographically in the vehicle-registration ledger, proceed to Step 6: Verify a document in a ledger.