Skip to main content

Understanding timestamps in TIM

The TIM Engine focuses on working with time-series data; as such, timestamps are a recurring thing accross all interactions with TIM. Additionallly, the occurence of timestamps is not limited to the time-series data itself: when working with the TIM platform, many other timestamps indicating events (such as creation, update, execution, completion...) will be encountered.

Working with timestamps easily becomes a mess, especially when multiple people and multiple time zones are involved. A small wrong assumption about a format can lead to significant consequences in outcome and decision-making. This illustrates the importance of clear conventions and standards when working with timestamps.

Alice in Belgium while Pete in Texas​

There are two types of timestamps you can come across when interacting with TIM, in particular:

  1. Transactional timestamps - these timestamps indicate when a certain transaction/operation occured such as creation of a workspace or update of a dataset.

  2. Dataset timestamps - timestamps in datasets as well as in configuration settings related to a dataset.

So how does TIM cope with these timestamps? And what about time zones?

Transactional timestamps​

Imagine Alice, who lives in Belgium. Alice creates a use case, and after getting meaningful results shares this use case with Pete. Pete lives in Texas. Both Alice and Pete would like to see this use case appear in the right place in the chronological order, thus with the timestamp indicating use case creation in their local time. TIM API stores and returns the timestamp in UTC time zone what clearly communicates to its clients (ex.g. TIM Studio), making the transformation into this local time straightforward. You can learn more about it in the transactional output timestamps section.

Now, what if Alice wants to get all the use cases that she created together with Pete for a specific period of time? Here we talk about transactional input timestamps. When getting the use cases from TIM API, Alice can specify the from-to interval to select subset of use cases. The input timestamps can either be in UTC time zone or in any other time zone by indicating the UTC offset. Since Alice is from Belgium, it is perhaps more convenient for her to use the CET/CEST time, hence she would append +01:00/+02:00 at the end of each timestamp. Whether it's in UTC or not, it is always unambiguous for TIM API which use cases to return.

Dataset timestamps​

Datasets are usually sampled in a certain time zone. Let's say Pete uploads a dataset collected in Texas. Midnight in Texas should be midnight also when exploring the dataset by Alice from Belgium. It is important TIM handles the time zone of the dataset correctly because the consecutive dataset manipulation and ML calculations such as:

depend on it. When uploading the dataset, Pete has more options how to provide the time zone information - specify the UTC offset on the level of individual timestamps, set the time zone (timeZoneName parameter) globally, or both. Each option has different consequences which you can learn more about in the time zones section. See also dataset timestamps section to read more about input/output dataset timestamps.