Just a second...

Using time series topics

A client can subscribe to a time series topic using a value stream, query to retrieve values within a range, append new values, or apply an edit event to override the value of an earlier event.

A time series topic stores an ordered series of events.

Each event stores a value, and has associated metadata.

An event value can be binary, double, int64, JSON, string or recordV2 value. Every event within a given time series has values with the same data type.

Table 1. Time series event metadata
Sequence number Timestamp Author
Unique number within time series, assigned when event created. Number increased by one with each new event. Timestamp for event. Not guaranteed unique. Principal that created the event. May be ANONYMOUS if session was not authorised.

Subscribing to a time series topic

Required permissions: read_topic

A client session can subscribe to a time series topic using a value stream to receive the latest events.

On subscribing to a time series topic, a session receives a set of the most recent events. By default, the latest event is sent. You can configure the TIME_SERIES_SUBSCRIPTION_RANGE property to determine how many recent events a new subscriber will receive.

Setting the DONT_RETAIN_VALUE property to true will prevent an initial event being sent, unless you have configured a subscription range.

Appending to a time series topic

Required permissions: update_topic

A session can append a value to a time series. The server will assign metadata to the event. The timestamp will be set to the current server time by default. The session can provide a timestamp, which must not be before the latest event stored by the time series topic. The author will be set to the authenticated principal of the client session. The sequence number will be one higher than the previous event in the time series.

Updating a time series topic

Required permissions: update_topic

A session can update a time series topic using the standard topic update methods. This allows for creating a topic with an initial value, using update constraints and update streams.

Editing a time series topic

Required permissions: update_topic, edit_time_series_events or edit_own_time_series_events

A client session can edit a time series. This provides a new value for an existing event.

The server retains both the original event and the edit event.

Subscribers receive two sets of metadata: the metadata for the edit event, and the metadata of the original event that was replaced.

Consider this example time series containing two events:

Sequence Value Type
0 A original event
1 B original event

Now an edit event is applied to the event with sequence number 0, changing the value to X. This information is now stored on the server:

Sequence Value Type
0 A original event
1 B original event
2 X edit of sequence 0

The edit event is assigned a sequence number like a normal event. Both the original event 0 and the edit event are retained on the server.

If an original event has several edit events, the latest edit event (the one with the highest sequence number) determines its current value. Each edit event refers to an original event, never to another edit event.

For example, suppose another edit event is applied to change the value of the first event from X to Y. Now the information stored looks like this:

Sequence Value Type
0 A original event
1 B original event
2 X edit of sequence 0
3 Y edit of sequence 0

Querying a time series topic

There are two ways to query a time series topic and select a range of events, which differ only in how they handle edit events.

Value range query

Required permissions: read_topic

A value range query returns part of a time series, using the latest available value for each event.

Events are returned in order of the original sequence number. If an event has never been edited, it is simply returned. If it has been edited, the most recent edit event is returned instead.

For example, consider the example time series above after the two edits have been applied. A value range query which selected the whole topic would return:
Sequence Value Original event sequence
3 Y 0
1 B -

The original value of the first event is not returned. The fact that the metadata of the original event is provided tells you that the event was edited.

A value range query is suitable for most use cases. If the client only needs the most recent value, or your application is not using edit events at all, use a value range query.

Edit range query

Required permissions: read_topic, query_obsolete_time_series_events

An edit range query can provide the history of values for events that have been edited. You are only likely to use this if you are implementing auditing or administrative features.

Because the history of edits is potentially sensitive information, an edit range query requires the additional query_obsolete_time_series_events permission.

There are two types of edit range query:

All edits

An all edits query returns all original events selected by the query, and all subsequent edit events that affect the originals. The results are provided in time series order.

An all edits query which selected all of the example above would return:

Sequence Value Original event sequence
0 A -
1 B -
2 X 0
3 Y 0

Both of the edit events for the original event 0 are returned.

This sort of query provides the maximum amount of information about the edit history of event values.

Latest edits

A latest edits query returns all original events selected by the query, plus the most recent edit event for each original event. The results are provided in time series order.

A latest edits query which selected all of the example above would return:

Sequence Value Original event sequence
0 A N/A
1 B N/A
3 Y 0

There were two edit events applied to the original event 0, but only the most recent edit event is returned in the query result.

This sort of query is useful if you need the original and latest value for an event, but not any intermediate values.

Note: Time series topics only retain a range of the most recent events (configured with the TIME_SERIES_RETAINED_RANGE property). By default, only the ten most recent events are retained, counting both original and edit events. Range queries only return edit events if the original event is selected. If you find that your queries do not return the results you expect, you may need to increase the retained range.