The effects of multiplier/offset or equation on parameter modified times

The eagle.io HTTP API allows for parameter data to be retrieved from a specified date range, and by default that date range refers to the record timestamps that should be returned by the query. However, by including timeQuery=MODIFIED in the URL, the API can instead return data based on the modified time of the records.

The modified time of each record is initially set as the time when it was ingested into the database. If a record in the database is subsequently changed via data editing, the modified time is updated to reflect the change. And if the record in the database is replaced (by ingesting updated values with the same timestamp, using a write mode of either Merge and overwrite or Replace existing), the modified time is updated.

Querying based on modified time allows for just the changed records to be specified. This is very useful if you have 1 million records in eagle.io that you need to extract via the API for use in an external system. After extracting the 1 million records, some may subsequently be edited via data editing. If you now want the external system to be updated with the results of the data editing, you don't want to extract all 1 million records again. Instead, you only want records that have been modified since the original extraction. So, by specifying a date range that starts after the original records were extracted, but before they were modified, and by setting timeQuery=MODIFIED in the API query, you can extract just the edited records.

What if the data being extracted was originally calculated by a process parameter, and then the process code is changed? In this case, the full range of the process (as defined by the entire historical range of the first input parameter) will be re-calculated, and the modified time will be updated accordingly to indicate that all records in the series have changed.

But what if you configure some kind of transform on the parameter? This is when you choose an multiplier/offset or equation to be applied to the raw data for state evaluation and display. For example, converting a raw value from degrees Celsius to degrees Fahrenheit using a multiplier and offset:

And the same conversion, this time using an equation:

When a transform (either multiplier/offset or equation) is configured on a parameter, the raw values in the database remain unchanged. However, when those values are extracted, the transform is applied before the values are shown in a UI view, or used to evaluate a state change, or returned by an API call. Because the raw values are unchanged, the modified times associated with those values are also unchanged. Therefore, if the consumer of the API result requires the transformed version of the raw values, you can't rely on modified time to know when a new transform is configured. In this situation, you would have to extract the entire data series again to ensure that the most recent transform has been applied to all the values in the result.

This table summarises when the modified time of the data is changed:

Being aware of exactly what operations will or won't update the modified time means you can have confidence in your expectations when making API calls that rely on the modified time.