Subscription Filtering

Event filtering

The default when subscribing is to receive all EventTypes. However, it is possible to limit the events that will be subscribed with some additional parameters. Here's an example requesting only EventType.trade:

// Initiate a getEqual request to the ContentGateway.
const requestHandle = client.streaming.getEqual({
    key: "MSFT.",
    fieldIds: [activCgApi.FieldId.FID_BID, activCgApi.FieldId.FID_ASK],
    subscription: {
        updateHandler: (update) => displayFields(update),
        type: activCgApi.Streaming.SubscriptionType.eventTypeFilterIncludeList,
        eventTypes: activCgApi.EventType.trade // Or an array of EventType.
    }
});

Note the additional type and eventTypes properties. Exclusion of event types is available using SubscriptionType.eventTypeFilterExcludeList.

Further information about event types is available here.

Conflated subscriptions

In addition to subscribing to full updates, or event-type filtered updates, the API allows the client to request conflated updates on a per subscription basis. Conflation is applied inside the ContentGateway per symbol using the event type of the update and requested conflation type to determine whether the update should be conflated or sent to the client.

Note that the event filtering described above is not available when requesting conflation: the subscription type must be SubscriptionType.full (the default).

Conflation is requested by specifying the conflation property of a requests's ISubscriptionParameters. Here's an example:

Example:

// Initiate a getEqual request to the ContentGateway.
const requestHandle = client.streaming.getEqual({
    key: "MSFT.",
    fieldIds: [activCgApi.FieldId.FID_BID, activCgApi.FieldId.FID_ASK],
    subscription: {
        updateHandler: (update) => displayFields(update),
        conflation: {
            type: activCgApi.Streaming.ConflationType.quote,
            interval: 200
        }
    }
});

Some description of the properties of IConflationParameters follows.

type

  • ConflationType.quote: all non-quote updates will be received without any delay. All quote data will be conflated such that only a single quote update is received within each period specified in the request. If a non-conflated event occurs such as a trade / correction / cancelation, then the interval will terminate prematurely and the current cache will be sent to the client followed by the non-conflated update. A new conflation interval will start at receipt of the next quote update.
  • ConflationType.trade: all quote and trade data is conflated over the provided period. Given that updates outside of trades or quotes are infrequent this will essentially limit the number of updates that any one symbol can produce to one update per period. At the end of a time period, the currently conflated updates are sent to the client and a new time period is started.

interval

The conflation interval in milliseconds that should be applied to this subscription must match one of the ContentGateway pre-configured values, which can be obtained from a call to getContentGatewayInfo.

In the event that a symbol has been subscribed to multiple times with differing conflation parameters, the client will receive updates conflated with the parameters constituting the least conflation. This selection favors conflation type over interval so if a client subscribes with ConflationType.quote at 500ms and ConflationType.trade at 100ms then the client will receive ConflationType.quote at 500ms.

dynamicConflationHandler

Optional. See the description of dynamic conflation that follows.

Updating a subscription's conflation parameters

The API supports modification of the conflation parameters being applied to each subscription in real-time. This removes the need for the client to unsubscribe and subsequently re-subscribe solely to change conflation parameters.

The conflation parameters are modified by calling the setConflationParameters method of the IRequestHandle returned from initiating a request:

// Initiate a getEqual request to the ContentGateway with 200ms quote conflation.
const requestHandle = client.streaming.getEqual({
    key: "MSFT.",
    fieldIds: [activCgApi.FieldId.FID_BID, activCgApi.FieldId.FID_ASK],
    subscription: {
        updateHandler: (update) => displayFields(update),
        conflation: {
            type: activCgApi.Streaming.ConflationType.quote,
            interval: 200
        }
    }
});

// Asynchronously iterate records.
for await (const record of requestHandle) {
}

// Update conflation to trade conflation at 100ms.
requestHandle.setConflationParameters({
    type: activCgApi.Streaming.ConflationType.trade,
    interval: 100
});

// Disable conflation.
requestHandle.setConflationParameters();

Dynamic conflation

The ContentGateway can support dynamic (adaptive) conflation. The availability of this feature is dependent on it being enabled in the ContentGateway itself and can be queried using getContentGatewayInfo and the isDynamicConflationAvailable property of the returned IContentGatewayInfo.

In broad terms, dynamic conflation allows a client’s subscription set to have variable intervals of conflation applied in an attempt to manage the bandwidth and/or server side resources used by a particular client. The client can enable dynamic conflation on a per subscription basis (assuming it is enabled on the ContentGateway) by setting dynamicConflationHandler to a function that will be called when the conflation level has changed by the ContentGateway.

There are two scenarios which will lead to the ContentGateway applying dynamic conflation to a client’s subscription set. Firstly if the ContentGateway determines that a client is not consuming data at a sufficient rate, then the it will increase the level of conflation being applied. Secondly the API allows a client to define a bandwidth limit for the session (see below) which the ContentGateway will attempt to maintain. The level of conflation will be increased if the client bandwidth usage exceeds the requested limit.

When dynamic conflation is applied to a client, the type of conflation is always changed to ConflationType.trade; this ensures that trade updates do not overwhelm the attempt to manage the resource usage. Note that this means dynamic conflation can be used without specifying a ConflationType itself.

If further conflation is required then the conflation period will be incremented to the next supported interval on the ContentGateway. These increments will continue to occur until the resource usage and/or bandwidth is within the required limits.

Any additional conflation applied to a client’s subscription set will be gradually removed once the resource usage returns to normal and the client bandwidth usage drops below the requested limit.

In the event that the ContentGateway changes the conflation parameters of a client subscription the client will be notified via the callback provided to dynamicConflationHandler, which is passed a IDynamicConflationInfo containing details of how the conflation has changed.

Setting the client bandwidth limit

The ContentGateway API allows a client to specify a bandwidth limit to be applied to their entire subscription set that was requested with dynamic conflation (i.e. it is not a per-subscription option). This will cause individual subscriptions with dynamic conflation enabled to have more conflation applied in the event that this bandwidth is exceeded.

The client bandwidth limit can be set by calling the IStreamingRequests method setConflationParameters.

Feed conflation

In addition to client requested conflation applied to subscriptions within the ContentGateway, an ACTIV data center may also provide bulk conflation on a per table basis. This functionality is provided via a standalone conflation application (Conflator) which sits in front of the ContentGateway.

When a Conflator is present in the data path, a standard subscription with no requested conflation will in fact be conflated since there is no non-conflated data. getContentGatewayInfo and then the returned feedConflationInfoList property can be used to obtain details of any tables which have bulk conflation applied and the conflation interval in use.

The Conflator has the capability to change the conflation interval being applied to each table in real-time. In the event that this occurs, an IClient instance can receive notification via the onFeedConflationUpdate provided to the connect method. IFeedConflationInfo passed to this callback will detail the table number which had its conflation interval changed and the previous and new values:

const client = await activCgApi.connect({
    url: "ams://cg-ny4-replay.activfinancial.com/ContentGateway:Service",
    userId,
    password,
    streaming: {
        onFeedConflationUpdate: (feedConflationInfo) => {
            // Feed level conflation has changed.
        }
    }
});

Also in this Section