Amazon Quantum Ledger Database (Amazon QLDB)
Developer Guide

Querying Document Metadata

An INSERT statement creates the initial revision of a document with a version number of zero. To uniquely identify each document, Amazon QLDB assigns a document ID as part of the metadata.

In addition to the document ID and version number, QLDB stores other system-generated metadata for each document in a table. This metadata includes transaction IDs, commit timestamps, and journal attributes.

Committed View

You can access this metadata by querying the committed view. This view returns documents from the system-defined table that directly corresponds to your user table. It includes the latest committed, non-deleted revision of both your data and the QLDB-generated metadata. To query this view, add the prefix _ql_committed_ to the table name in your query. The prefix _ql_ is reserved in QLDB for system objects.

SELECT * FROM _ql_committed_VehicleRegistration

Using the data previously inserted in Creating Tables and Inserting Documents, the output of this query shows the system contents of each document's latest non-deleted revision. The system document includes the vehicle registration data nested in the data field, metadata nested in the metadata field, its SHA-256 hash value, and the location in the journal where it was committed.

{ blockAddress:{ strandId:"JdxjkR9bSYB5jMHWcI464T", sequenceNo:14 }, hash:{{wCsmM6qD4STxz0WYmE+47nZvWtcCz9D6zNtCiM5GoWg=}}, data:{ VIN: "1N4AL11D75C109151", LicensePlateNumber: "LEWISR261LL", State: "WA", City: "Seattle", PendingPenaltyTicketAmount: 90.25, ValidFrom: 2017-08-21T, ValidTo: 2020-05-11T, Owners: { PrimaryOwner: { PersonId: "294jJ3YUoH1IEEm8GSabOs" }, SecondaryOwners: [{ PersonId: "5Ufgdlnj06gF5CWcOIu64s" }] } }, metadata:{ id:"3Qv67yjXEwB9SjmvkuG6Cp", version:0, txTime:2019-06-05T20:53:321d-3Z, txId:"HgXAkLjAtV0HQ4lNYdzX60" } }, { blockAddress:{ strandId:"JdxjkR9bSYB5jMHWcI464T", sequenceNo:14 }, hash:{{wPuwH60TtcCvg/23BFp+redRXuCALkbDihkEvCX22Jk=}}, data:{ VIN: "KM8SRDHF6EU074761", LicensePlateNumber: "CA762X", State: "WA", City: "Kent", PendingPenaltyTicketAmount: 130.75, ValidFrom: 2017-09-14T, ValidTo: 2020-06-25T, Owners: { PrimaryOwner: { PersonId: "IN7MvYtUjkp1GMZu0F6CG9" }, SecondaryOwners: [] } }, metadata:{ id:"JOzfB3lWqGU727mpPeWyxg", version:0, txTime:2019-06-05T20:53:321d-3Z, txId:"HgXAkLjAtV0HQ4lNYdzX60" } }

These documents include the following system attributes:

  • blockAddress—The location of the block in your ledger's journal where the document revision was committed. An address, which can be used for cryptographic verification, 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.

    Note

    Both documents in this example have an identical blockAddress with the same sequenceNo. Because these documents were inserted within a single transaction (and in this case, in a single statement), they were committed in the same block.

  • hash—The SHA-256 value that uniquely represents the document revision. The hash covers the data and metadata fields and can be used for cryptographic verification.

  • metadata—The document's metadata attributes.

    • id—The system-assigned document ID.

    • version—The zero-based integer that increments with each document revision.

    • txTime—The timestamp when the document revision was committed to the journal.

    • txId—The unique ID of the transaction that committed the document revision.

To learn how to query the document ID field in the default user view, see Using the BY Clause to Query Document ID.

On this page: