This article describes the concept of creating structured views of multiple Twins on the Trusted Twin platform.
The purpose of this article is to provide system architects and developers with conceptual knowledge required to design solutions on the Trusted Twin platform. In order to consult developer resources, please go to the Trusted Twin docs website.
5 min read.
Shared processes (i.e., processes involving multiple cooperating organizations) usually operate on shared objects (i.e., Twins). Twins tie together knowledge provided by partners and act as conceptual “brackets” for the data. Therefore, they are the most important objects in operational data sharing.
Read more: Shared object
When working with shared objects, sometimes it is necessary to access structured views of multiple Twins. Such structured views can be useful for, among others, advanced search or ML/AI training or analysis.
The Trusted Twin platform supports two types of such structured views: Indexes and Timeseries. Both structured views, once defined and configured, are updated automatically every time there is a change to the Ledgers’ properties.
The Trusted Twin platform stores Indexes and Timeseries tables in dedicated instances of relational databases. The instances are created individually for each account to provide the highest possible level of security (i.e., data separation). Additionally, they allow direct database access and execution of SQL queries for the account.
Indexes hold a set of properties of selected Twins (i.e., values from account’s Ledger attached to the given Twin). Each Index is a separate database table and a single account can create multiple Indexes.
An Index is defined as:
- a Twin selection rule (Read more: Rules),
- list of properties and their types,
Create an Indexes table
- list of templates for calculating property values (Read more: Templates).
Every time the value of an Entry in the Twin’s Ledger is changed, the Twin selection rule is evaluated. If the rule resolves to
True, then the values of properties are calculated and the corresponding row is inserted or updated. If the rule evaluates to
False, then the new row is not inserted or the corresponding row is deleted. Therefore, a given Index stores only information about the Twins selected by the Twin selection rule. A single Twin can be represented in a single Index only once.
Timeseries hold a series of measurements. They differ from Indexes in that the primary key is defined as a tuple containing a Twin UUID and a timestamp. Similarly as with Indexes, each Timeseries is a separate database table and a single account can create multiple Timeseries tables.
Each Timeseries is defined as:
- a list of dimensions and their types,
- a list of measurements and their types,
- a timestamp default template,
- default templates for dimensions,
- default templates for measurements.
Create a Timeseries table
Timeseries, unlike Indexes, do not use Twin selection rules. It is because they are configured as Entry properties directly in the Ledger. Every time a value of an Entry with a Timeseries property set is changed, the corresponding row holding the timestamp, dimensions and measurements is appended to the Timeseries table. Once the rows are appended, they stay in the Timeseries table for the defined retention period.
Tips & tricks
- If you need historical values of Ledger Entries, but do not require structured views of Twins, you can use the standard History service.
- Indexes and Timeseries are configured in a slightly different way – while Indexes are configured outside the Ledger and are based on Twin selection rules, Timeseries are configured directly in the Ledger Entries as properties.
- The Trusted Twin platform allows for direct access to Indexes and Timeseries tables.