Data organization

Data is structured within the Azure confidential ledger in two primary ways: transaction ID and collection ID (or subledger ID). Each write operation generates a unique transaction ID, which you can use to retrieve entries, obtain receipts, or perform other operations. Collection IDs are user-specified keys (optional) that help group related entries, allowing for more efficient data retrieval and management. This article shows examples demonstrating how to create ledger entries, retrieve entries by transaction ID, and list entries within a range or collection.

You can also organize and query data on public ledgers by using tags. Tags improve data management within collections by acting as secondary keys.

Transaction ID

Every write that is written to the ledger generates a transaction ID, which is returned in the response from the write endpoint. It looks like the following example:

sample_entry = {"contents": "Hello world!"}
append_result = ledger_client.create_ledger_entry(entry=sample_entry)
print(f"Transaction ID: {append_result['transactionId']}")

Response:

Transaction ID: 2.10

The contents of a ledger entry are limited in size. For the current limit, see Azure confidential ledger limits.

The transaction ID in the response can be used to retrieve the entry or do other operations, such as retrieving the receipt. It's also possible to get a list of entries by providing a range of transaction ID parameters similar to the following example.

# Get the latest transaction to the ledger default/global table
get_result = ledger_client.get_current_ledger_entry()

# Get one transaction
get_result = ledger_client.get_ledger_entry(transaction_id="2.10")

# Get a list of transactions within a range
list_result = ledger_client.list_ledger_entries(from_transaction_id="2.1", to_transaction_id="2.50")

Note

Reading historical entries can return a Loading state while the ledger loads them. Range queries can return a nextLink to the next page of results. Send the retry or the request for the next page within one minute. Otherwise, the ledger discards the data it loaded, and the request returns Loading again.

Collection ID

A Collection ID (also known as Subledger ID) in Azure Ledger refers to a user-specified optional key for entries written to the ledger. It provides a way to add a key or marker to the data being written which can then be used to retrieve the data later on.

Collection IDs are strings with a limited length. For the current limits, see Azure confidential ledger limits.

Use collection IDs to group related entries. Because the number of collections in a ledger is limited, don't create a unique collection ID for every entry. To identify a single entry, use its transaction ID. If you don't specify a collection ID, the data is written to the default collection (subledger:0).

In order to specify a collection ID, the user has to specify the collectionID parameter during write request.

sample_entry = {"contents": "Secret recipe ingredients...!"}
append_result = ledger_client.create_ledger_entry(entry=sample_entry, collection_id="icecream-flavors")

The transaction can then be retrieved by specifying the collection ID and the transaction ID during a read operation or by specifying just the collection ID in list operations.

# Get the latest transaction in a collection
get_result = ledger_client.get_current_ledger_entry(collection_id="icecream-flavors")

# Get one specific entry in a collection
get_result = ledger_client.get_ledger_entry(transaction_id="2.68", collection_id="icecream-flavors")

# Get all entries in a collection
list_result = ledger_client.list_ledger_entries(collection_id="icecream-flavors")
for entry in list_result:
    print(f"Transaction ID: {entry['transactionId']}")
    print(f"Contents: {entry['contents']}")

It's also possible to get a list of entries within a collection by specifying both the collection ID and a range of Transaction ID parameters.

list_result = ledger_client.list_ledger_entries(from_transaction_id="2.1", to_transaction_id="2.50", collection_id="icecream-flavors")

Tags

To use tags, use REST API version 2026-02-23 or later.

Additionally, this feature is limited to Confidential Ledgers that are of the Public Ledger Type. Private Ledger Type is not supported.

Tags improve management of data within a collection by acting as secondary keys to a collection of data. Tags have limits on their length, the characters they can contain, the number of tags per write, and the number of tags in a ledger. For the current limits, see Tag limits per write and Ledger data limits.

In order to use tags inside a collection, tags parameter needs to be specified.

# multiple tags can be specified using commas.
append_result = ledger_client.create_ledger_entry(entry=sample_entry, collection_id="icecream-flavors", tags="chocolate,vanilla")

Retrieving entries can be done as before:

# Get all entries in a collection which has a specified tag. Only one tag is supported per query during a Read operation. Only list/ranged operations are supported with tags.  
list_result = ledger_client.list_ledger_entries(collection_id="icecream-flavors", tag="chocolate")
for entry in list_result:
    print(f"Transaction ID: {entry['transactionId']}")
    print(f"Contents: {entry['contents']}")

Sample scenarios

The following scenarios can help you decide when to use collection IDs versus tags.

Scenario Recommended approach Why
You write general records and mostly read by transaction ID or latest entry. Use the default collection ID (subledger:0). This approach keeps data organization simple and avoids managing many collection IDs.
You need strict logical separation of data sets, such as tenant-specific or workload-specific isolation. Use dedicated collection IDs for each logical group. Group-level collection IDs make it easier to isolate and list records by boundary.
You need query-oriented lookups at a finer granularity, including per-entry categorization. Use tags within a shared collection instead of creating a unique collection ID per entry. You can achieve similar query outcomes without creating and managing a unique collection ID for every entry.

If your main goal is query flexibility, start with tags and add more collection IDs only when clear isolation boundaries are required.

Keep in mind that the number of collections and tags in a ledger is limited. For more information, see Azure confidential ledger limits.

Next steps

  • Last updated on