Just a second...

Properties of topics

When you create a topic, you can specify properties that the topic has. The available properties depend on the topic type.

The following table shows which properties are available. Some property names have been abbreviated; see below the table for the full names.
Table 1. Properties available for topics of each type
Type PUBLISH VALUES ONLY DONT RETAIN VALUES SLAVE MASTER TOPIC TIDY ON UNSUB. TIME SERIES EVENT VALUE TYPE TIME SERIES RETAINED RANGE TIME SERIES SUBSCR. RANGE VALIDATE VALUES SCHEMA
JSON Supported Supported   Supported       Supported  
Binary Supported Supported   Supported       Supported  
String Supported Supported   Supported       Supported  
Int64   Supported   Supported       Supported  
Double   Supported   Supported       Supported  
Time series Supported Supported   Supported Supported REQUIRED Supported Supported Supported  
Routing       Supported          
Slave     Supported REQUIRED Supported          
RecordV2   Supported   Supported       Supported Supported
DEPRECATED: Record       Supported          
DEPRECATED: Single value       Supported          
DEPRECATED: Stateless       Supported          
PUBLISH_VALUES_ONLY
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.

DONT_RETAIN_VALUE
If set to true, the latest value of the topic is not retained by the Diffusion™ server or the client that publishes it. New clients that subscribe do not receive an initial value. No value will be returned for fetch operations that select the topic.

For time series topics, if DONT_RETAIN_VALUE is set to true, time series events are still retained, but the latest value is not stored separately.

The DONT_RETAIN_VALUE property is useful for applications like a feed of news items, or for values that are only valid at the moment of publication. You can combine this with VALIDATE_VALUES.

Using DONT_RETAIN_VALUE reduces the topic memory footprint, but disables delta streaming. Disabling delta streaming is likely to increase the bandwidth used unless subsequent values are unrelated.

This property replaces the deprecated stateless topic type which sends untyped byte data and requires clients to interpret and validate the data.

SLAVE_MASTER_TOPIC
The path to the topic that acts as the master topic to a slave topic. A topic is not required to exist at this path at the time the slave topic is created.
TIDY_ON_UNSUBSCRIBE
If set to true, when a session unsubscribes from the topic, any updates for the topic that are still queued for the session are removed.

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.

TIME_SERIES_EVENT_VALUE_TYPE
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:
  • json
  • binary
  • string
  • int64
  • double
  • record_v2
TIME_SERIES_RETAINED_RANGE
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.

TIME_SERIES_SUBSCRIPTION_RANGE
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.

VALIDATE_VALUES
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.
SCHEMA
Optionally, define valid records and fields of a recordV2 topic.

A recordV2 topic contains records, which can be divided into fields. The schema names the records and fields and provides a mechanism for direct access to the fields. The schema is also used to validate the data to ensure it complies with the schema definition. The schema property is supplied as a JSON string that can be generated from a Schema object.

If no schema is provided, the topic data can be free format.

Range expressions

A range expression can contain the following constraints:
A limit constraint
A limit constraint specifies the maximum number of events from the end of the time series.
For example, the following expression requests the five most recent events:
limit 5
A last constraint
A last constraint specifies the maximum duration of events from the end of the time series. The duration is expressed as an integer followed by one of the following time units:
  • MS – milliseconds
  • S – seconds
  • H – hours
For example, the following expression requests all recent events that are no more than 30 seconds older than the latest event:
last 30s
Both a limit and a last constraint
For example, the following expression requests the ten most recent events that are no more than one minute older than the latest event:
last 60s limit 10
If a range expression contains multiple constraints, the constraint that selects the smallest range is used.
Range expressions are not case sensitive.