Make subscriptions more specific

You’ll have seen in Subscribing to Data and Receiving Updates how to make a typical subscription to data. But what if you want to make more specific subscriptions?

You do this using StreamLink’s subscription parameters. The client can supply various types of parameter to a subscription request, to ensure that only specifically required data is returned.

Filtering fields

Supported data types: records (since 6.0.0), generic objects (since 8.0.0)

When a client subscribes to a subject it can specify a fields parameter to restrict the fields to be returned, so that Liberator does not waste bandwidth sending fields that are irrelevant to the client.

Field filter example
streamLink.subscribe(subject, listener, {fields: ["field1", "field2", ...]});

Filtering record updates

Supported data types: records (since 6.0.0), generic objects (since 8.0.0)

When a client subscribes to a subject it can specify a filter parameter that restricts the subscription updates received. The filtering is done on the Liberator, rather than in the client, so that network traffic and client side processing are reduced.

Data structured as Records can be filtered using filter expressions containing the following operators:

Operator Meaning

|

or

&

and

=

equal to

!=

not equal to

<

less then

>

more than

<=

less than or equal to

>=

more than or equal to

~

Provides matching for items in comma- separated string lists. For example, ~abc matches a field in "xyz,abc,def" but not in "xyzabcdef"

( )

Parenthesis – perform these filters first

For example, the filter expression below selects only those records where both the BidSize and AskSize fields each contain a value greater than 1,000:

(BidSize > 1000) & (AskSize > 1000)

There are two types of record filter:

Update filters

An update filter is applied to the data within a particular update of the data item. An update record does not necessarily contain all the fields that the client originally subscribed to within the item. If the filter is dependent on a field that is not present within an update, the filter operation will result in "no match", and the Liberator will not send the update to the client.

Update filter example
streamlink.subscribe(subject, listener, {filter: {value: "(BidSize > 1000) & (AskSize > 1000)", image: false}}
Image filters

An image filter is applied after the data within a particular update has been applied to the image of the data item. The filter may specify a field that is not present within the update. When this happens, the Liberator uses its cached value of the field to determine whether the update matches the filter.

Image filter example
streamlink.subscribe(subject, listener, {filter: {value: "(BidSize > 1000) & (AskSize > 1000)", image: true}}

The following table shows an example of the difference in behaviour between update filters and image filters. In both cases the filter used is (BidSize > 1000) & (AskSize > 1000). Each row of the table represents the result of an update, where the updates have been applied to the same record item in the order 1, 2, 3, 4, 5. none means the field in question was not updated:

Update no Bid BidSize Ask AskSize Matches Update Filter? Matches Image Filter?

1

54.25

1500

55.00

2000

Yes

Yes

2

54.00

2000

none

none

No

Yes

3

54.50

500

none

none

No

No

4

54.25

1500

54.75

500

No

No

5

54.00

2000

54.75

1500

Yes

Yes

Filtering news headlines

News headlines can be filtered by specifying a news filter when creating an object. The filter expression consists of news codes and/or whole words to search for. A news filter expression can contain the following operators:

Character Meaning

[space]

or

|

or

+

and

&

and

-

and

=

equal to

!

not

~

not

'

start or end of free text search string

"

start or end of free text search string

( )

Parenthesis – perform these filters first

For example, the filter expression below selects only those news headlines with code UKX, or where the headline contains the phrase "stock rises" and does not contain the phrase "preference":

UKX | ('stock rises' & (!'preference'))

News codes can only contain capitals and numbers, and have a maximum length defined in the Liberator configuration. Capitalised items in the headline that are longer than the maximum news code length are treated as text for the purposes of searching, as are items in mixed case and lower case. Use ' or " to force a text search. For example 'UKX' selects news headlines containing the text "UKX".

Subscribing to a container window

When a client subscribes to a container it can specify a window into the container, that is, the start and end rows of the container data that are to be returned. The Liberator only sends the client updates for the items currently in the window.

The client can ask StreamLink to move the window on the container (for example because the end-user has scrolled down through the displayed view of the container window). StreamLink will then ask Liberator to supply the data for the items that are currently in the scope of the window.

This server-side paging capability helps reduce the processor and memory requirements on the client in situations where the container refers to a large number of items, but the end-user views just a few of them at a time through a small scrollable window. Rather than handling updates for the entire list, even though only a small part of it is on view, the client merely has to manage updates for the few items in the container window (which maps onto the display window).