Use Timed Value Types
Types that mixin TimedValue allow you to associate a timestamp with a value. Used in conjunction with types that mixin TimedValueHistory, it is possible to keep a history of what those values were over time. This can be useful for things like tracking when the status of an account was changed over its lifespan.
Timed Value Types
There are several varieties of timed values that support different scenarios:
- TimedValue - track single values (of any value type) with a single timestamp.
- TimedIntervalValue - similar to TimedValue but uses a time range instead of a single timestamp.
- TimedCharacteristic - similar to TimedValue but instead of just a value, also has a name associated with each value.
- TimedRelation - similar to TimedValue but instead of a value there are separate from/to fields representing that a relation existed between the from/to at the specified timestamp.
There are also additional combinations of the above (for example, TimedIntervalRelation).
When to use TimedValue versus TimedCharacteristic
When you have a specific attribute that is known at the time of data modeling, using TimedValue is preferable.
This enables you to create individual fields for those values and track their history automatically. This makes sense for things like an account history.
If, however, there are many attributes describing something that can change over time, and/or those attributes are not all known at the time of data modeling, TimedCharacteristic is a better choice.
With TimedCharacteristic, you can independently track the values of multiple attributes related to a parent without having to make any schema changes when new attributes must be tracked.
Maintaining the latest Timed Value
For scenarios such as an account status, it is frequently desirable to maintain the latest value of the status on the account while also maintaining the history of changes to the status over time.
To facilitate this, you can create a field in a Type that holds the TimedValue, which is the latest value, and keep it synchronized with the history by using a timedValueHistoryField field for the TimedValueHistory.
The following example shows how this is done.
/**
* Status set fields
*
* Service Agreement status history in a descending order over time.
*/
@db(order='descending(timestamp)')
serviceAgreementStatusSet: [ServiceAgreementStatusSet](parent)
/**
* Latest status of service agreement.
*/
@db(timedValueHistoryField='serviceAgreementStatusSet')
serviceAgreementStatus: ServiceAgreementStatusIn this example, ServiceAgreementStatus mixes in TimedValue and ServiceAgreementStatusSet mixes in TimedValueHistory. The serviceAgreeStatus field holds the latest status for a serviceAgreement.
The timedValueHistoryField holds the history of statuses for the service agreement.
With this configuration, when input data specifies a new value for serviceAgreementStatus, an entry is added to the history. The serviceAgreementStatus is automatically maintained to hold the latest value.
serviceAgreementStatus has eventually consistent behavior. The computed value may not always reflect the current state based on the most recent entry in serviceAgreementStatusSet, depending on when the query is made. Factors that affect stored calc computation (such as disableAsyncProcessing in UpsertSpec or full task nodepool utilization) will also delay updates to serviceAgreementStatus.