RecordV2 topics
A topic that streams data in recordV2 format, where the data is divided into multiple records, each of which can contain multiple fields. RecordV2 topics are stateful: each topic stores a value consisting of one or more records on the Diffusion™ server .
You can optionally define the format of the data by using a schema that is associated with the recordV2 topic. You can use a schema to validate the data at the server. A schema also provides a convenient way of building a topic value using the fields defined within the schema, or interpreting a topic value in terms of named records and fields. For more information, see RecordV2 schema.
If you choose not to provide a schema, the data is treated as free format: the meaning of each field is up to your application, and Diffusion does not perform any validation.
.Why use a recordV2 topic?
A recordV2 topic enables multiple fields to be maintained in the same topic as part of a composite data type. All updates made at the same time to fields on a record topic are sent out to the client together. This enables a set of fields to be treated as a transactional group.
Deltas of change are calculated at the server such that only those fields that have changed since the last update are sent out to the subscribed clients. This ensures that the minimum amount of data is sent to clients.
Properties of a recordV2 topic
- 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. Using an update stream will send complete values to the server, instead of deltas. Disabling delta streaming is likely to increase the bandwidth used unless subsequent values are unrelated.
This property replaces the obsolete stateless topic type which was removed in Diffusion 6.2.
- 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.
- 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.
- 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. - CONFLATION
- 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:
- off
- conflate
- unsubscribe
- always
The default is "conflate".Note: Time series topics do not allow a conflation policy of 'conflate' or 'always'. They default to 'off'. You can set a conflation policy of 'unsubscribe'.See Using conflation for details of the policies.
- OWNER
- 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.
- REMOVAL
- 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.
- PERSISTENT
- 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 recordV2 topic
RecordV2 replaced the older record topic type, which was removed as of Diffusion 6.2. You can migrate your applications from record topics to recordV2 topics with minimal changes. Using recordV2 instead of the obsolete record type is required to use topic persistence and topic replication.
The data within a recordV2 topic can either be free format or constrained by a schema. If no schema property is specified, the topic will be treated as free format.
Update a recordV2 topic with a value updater. See Updating topics for more information about value updaters.
Receive data from a recordV2 topic with a value stream. See Using streams for subscription for more information.