Why use a time series topic?

A time series topic holds a sequence of events. Time series topics are useful for collaborative applications such as chat rooms. Multiple users can concurrently update a time series topic.

Each event in a time series topic has a value. Each time series topic has an associated data type which determines what type of value its events have: binary, double, int64, JSON, string or recordV2.

All the events in a given time series topic must have the same value type.

Each event is assigned metadata by the Diffusion™ server . This metadata consists of a sequence number, a timestamp, and an author (where the author is the principal used by the client session that creates the event).

A time series is an append-only data structure. A session can update the topic by providing a new event, which the server will append to the end of the time series. A session can also edit an existing event in time series, providing a new value. Editing an event does not remove or modify the original event, but instead appends an edit event to the end of the time series. Edit events have an additional metadata field, the sequence number of the original event, allowing subscribers to associate the new value with the replaced value.

You can subscribe to events that are published to a time series topic and receive updates in the same way as for other topics. New subscribers also receive an initial subset of the most recent events. You can configure a subscription range to control how far back in time the initial set goes.

You can query a time series topic to receive a range of events based on the timestamp or sequence number of the events in a series.

By default, queries return a merged view of a time series that includes edit events in the place of the original events. A session with the QUERY_OBSOLETE_TIME_SERIES_EVENTS permission can submit a modified query which returns an unmerged view that includes both original events and the edit events that replace them.

Properties of a time series topic

Considerations when using a time series topic

All the events in a time series topic are stored in memory on the Diffusion server . If the Diffusion server is restarted, the events in the time series are lost unless topic persistence is enabled.

A time series topic retains a range of the most recent events. Older events are discarded. By default, only the ten most recent events are retained (this includes edit events). You can configure the "retained range" property to retain more events.

If you are considering using PUBLISH_VALUES_ONLY for a time series topic, use DONT_RETAIN_VALUE, which has the same effect of disabling delta streaming, but additionally saves memory.

A query against a time series topic only returns edit events that refer to original events in the view range of the query. If the original event is no longer stored on the server due to the retained range, related edit events will never be returned. These "orphaned" edit events will stay on the server until more events have been appended and they are pushed out of the retained range.

If subscribing to a time series topic and using a value stream to receive data, ensure that the client adds the value stream before subscribing to the topic to receive all events in the configurable window. If the client session adds the value stream after it subscribes to the time series topic, the client session only receives the latest event on the time series topic.