A time series topic holds a sequence of events.
Java™, Android™, .NET and Apple®
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
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
When you create a time series topic you must specify the following property in the topic
- Set this to the type name of a Diffusion
data type. All events in the time series are of this data type. The type name can be
one of the following values:
You can also specify the following optional properties in
the topic specification:
- By default, delta streaming is enabled.
If this property is set to true, delta streaming is disabled and
all values are published in full.
If there is little or no relationship between one value published to a topic and the next,
delta streams will not reduce the amount of data transmitted. For such topics, it is
better to set PUBLISH_VALUES_ONLY.
- If set to true, when a session unsubscribes from
the topic, any updates for the topic that are still queued for the session are
There is a performance overhead to using this option as the client queue must be
scanned to find topic updates to remove, however it may prove useful for preventing
unwanted data being sent to sessions. This property is disabled by default.
- Set this to a range expression that specifies the range of events
retained by a time series topic. When a new event is added to the time series, older
events that fall outside of the range are discarded. If the property is not specified,
a time series topic retains the ten most recent events.
For more information about
range expressions, see Range expressions.
- Set this to a range expression that specifies the range of
events sent to all new subscribers.
If a range expression is specified for this
property, the specified subscription range is sent to the client session. This is
true whether delta streams are enabled for the topic or not. However, to receive all
the events in the specified range, the subscribing client session must register a
stream before it subscribes to the topic. If a stream is not registered before
subscription, the session receives only the latest value.
If the property is not specified, new subscribers will be sent the latest event if
delta streams are enabled for the topic and no events if delta streams are disabled
for the topic.
For more information about range expressions, see Range expressions.
- If set to true, the topic rejects updates that would
create invalid instances of the topic's data type.
If set to anything other than
true, no validation is performed and all values are streamed to
subscribing clients whether they are valid data or not.
Validation has a performance overhead and is disabled by default.
Note: If validation is disabled and the value provided is not valid, the client might
produce errors or other unexpected behavior. The exact error varies depending on the
client platform. To avoid this, use the client-side validation method provided by
the Diffusion API.
- Used to set a conflation policy for the topic. Conflation can
merge or discard topic updates to reduce server memory and network data usage.
The supported values are:
The default is "conflate".
See Using conflation for details of the policies.
- Used to set a security principal as the owner of the topic.
The principal receives READ_TOPIC, MODIFY_TOPIC
and UPDATE_TOPIC privileges.
The format of the property value is:
$Principal is "name"
where name is the name of the principal.
- Used to set a topic removal policy.
The property is an expression which defines the conditions which will trigger automatic removal
of the topic or of a set of topics specified with an optional selector.
See Removing topics automatically for details of the expression format.
- Used to disable persistence for a topic.
If set to "false", the topic will not be persisted, even if persistence
is enabled for the server.
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
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