Core concepts and terminology in Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)
QLDB data object modelJournal-first transactionsQuerying your dataData storageQLDB API modelNext steps

Core concepts and terminology 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.

This section provides an overview of the core concepts and terminology in Amazon QLDB, including ledger structure and how a ledger manages data. As a ledger database, QLDB differs from other document-oriented databases when it comes to the following key concepts.

QLDB data object model

The fundamental data object model in Amazon QLDB is described as follows:

  1. Ledger

    Your first step is to create a ledger, which is the primary AWS resource type in QLDB. To learn how to create a ledger, see Step 1: Create a new ledger in Getting started with the console, or Basic operations for Amazon QLDB ledgers.

    For both the ALLOW_ALL and STANDARD permissions modes of a ledger, you create AWS Identity and Access Management (IAM) policies that grant permissions to run API operations on this ledger resource.

    Ledger ARN format:

    arn:aws:qldb:${region}:${account-id}:ledger/${ledger-name}

  2. Journal and tables

    To start writing data in a QLDB ledger, you first create a table with a basic CREATE TABLE statement. Ledger data consists of revisions of documents that are committed to the ledger's journal. You commit document revisions to the ledger in the context of user-defined tables. In QLDB, a table represents a materialized view of a collection of document revisions from the journal.

    In the STANDARD permissions mode of a ledger, you must create IAM policies that grant permissions to run PartiQL statements on this table resource. With permissions on a table resource, you can run statements that access the current state of the table. You can also query the revision history of the table by using the built-in history() function.

    Table ARN format:

    arn:aws:qldb:${region}:${account-id}:ledger/${ledger-name}/table/${table-id}

    For more information about granting permissions on a ledger and its associated resources, see How Amazon QLDB works with IAM.

  3. Documents

    Tables consist of revisions of QLDB documents, which are datasets in Amazon Ion struct format. A document revision represents a single version of a sequence of documents that are identified by a unique document ID.

    QLDB stores the complete change history of your committed documents. A table lets you query the current state of its documents, while the history() function lets you query the entire revision history of a table's documents. For details on querying and writing revisions, see Working with data and history.

  4. System catalog

    Each ledger also provides a system-defined catalog resource that you can query to list all of the tables and indexes in a ledger. In the STANDARD permissions mode of a ledger, you need the qldb:PartiQLSelect permission on this catalog resource to do the following:

    • Run SELECT statements on the system catalog table information_schema.user_tables.

    • View table and index information on the ledger details page on the QLDB console.

    • View the list of tables and indexes in the PartiQL editor on the QLDB console.

    Catalog ARN format:

    arn:aws:qldb:${region}:${account-id}:ledger/${ledger-name}/information_schema/user_tables

Journal-first transactions

When an application reads or writes data in a QLDB ledger, it does so in a database transaction. All transactions are subject to limits as defined in Quotas and limits in Amazon QLDB. Within a transaction, QLDB does the following steps:

  1. Read the current state of the data from the ledger.

  2. Perform the statements provided in the transaction, and then check for any conflicts using optimistic concurrency control (OCC) to ensure fully serializable isolation.

  3. If no OCC conflicts are found, return the transaction results as follows:

    • For reads, return the result set and commit the SELECT statements to the journal in an append-only manner.

    • For writes, commit any updates, deletes, or newly inserted data to the journal in an append-only manner.

The journal represents a complete and immutable history of all the changes to your data. QLDB writes one chained block to the journal in a transaction. Each block contains entry objects that represent the document revisions that you insert, update, and delete, along with the PartiQL statements that committed them.

The following diagram illustrates this journal structure.

Amazon QLDB journal structure diagram showing a set of chained blocks that make up a strand, and the sequence number and block hash of each block.

The diagram shows that transactions are committed to the journal as blocks that contain document revision entries. Each block is hashed and chained to subsequent blocks for verification. Each block has a sequence number to specify its address within the strand.

Note

In Amazon QLDB, a strand is a partition of your ledger's journal. QLDB currently supports journals with a single strand only.

For information about the data contents in a block, see Journal contents in Amazon QLDB.

Querying your data

QLDB is intended to address the needs of high-performance online transaction processing (OLTP) workloads. A ledger provides queryable table views of your data based on the transaction information that is committed to the journal. A table view in QLDB is a subset of the data in a table. Views are maintained in real time, so that they're always available for applications to query.

You can query the following system-defined views using PartiQL SELECT statements:

  • User – The latest active revision of only the data that you wrote in the table (that is, the current state of your user data). This is the default view in QLDB.

  • Committed – The latest active revision of both your user data and the system-generated metadata. This is the full system-defined table that corresponds directly to your user table.

In addition to these queryable views, you can query the revision history of your data by using the built-in History function. The history function returns both your user data and the associated metadata in the same schema as the committed view.

Data storage

There are two types of data storage in QLDB:

  • Journal storage – The disk space that is used by a ledger's journal. The journal is append-only and contains the complete, immutable, and verifiable history of all the changes to your data.

  • Indexed storage – The disk space that is used by a ledger's tables, indexes, and indexed history. Indexed storage consists of ledger data that is optimized for high-performance queries.

After your data is committed to the journal, it's materialized into the tables that you defined. These tables are optimized for faster and more efficient queries. When an application uses the transactional data API to read data, it accesses the tables and indexes that are stored in your indexed storage.

QLDB API model

QLDB provides two types of APIs that your application code can interact with:

  • Amazon QLDB – The QLDB resource management API (also known as the control plane). This API is used only for managing ledger resources and for non-transactional data operations. You can use these operations to create, delete, describe, list, and update ledgers. You can also verify data cryptographically, and export or stream journal blocks.

  • Amazon QLDB Session – The QLDB transactional data API. You can use this API to run data transactions on a ledger with PartiQL statements.

    Important

    Instead of interacting directly with the QLDB Session API, we recommend using the QLDB driver or the QLDB shell to run data transactions on a ledger.

    • If you're working with an AWS SDK, use the QLDB driver. The driver provides a high-level abstraction layer above the QLDB Session data API and manages the SendCommand operation for you. For information and a list of supported programming languages, see Getting started with the driver.

    • If you're working with the AWS CLI, use the QLDB shell. The shell is a command line interface that uses the QLDB driver to interact with a ledger. For information, see Using the Amazon QLDB shell (data API only).

For more information about these API operations, see the Amazon QLDB API reference.

Next steps

To learn how to use a ledger with your data, see Working with data and history in Amazon QLDB and follow the examples that describe the process of creating tables, inserting data, and running basic queries. This guide explains how these concepts work in depth, using sample data and query examples for context.

To get started quickly with a sample application tutorial using the QLDB console, see Getting started with the Amazon QLDB console.

For a list of the key terms and definitions described in this section, see the Amazon QLDB glossary.