Refiner subject syntax

Avoid filtering or sorting on record fields that are subject to frequent updates. Frequent updates can have an adverse affect on the performance of Caplin Refiner, Liberator, and the requesting clients.

To use Refiner to filter, sort, and group data in a container, prepend the container’s subject with /FILTER and append the container’s subject with ? followed by a string of Refiner parameters.

Syntax diagram:

At least one of the following parameters is required: filter, sort, groupby

The mapsuffix parameter is normally added dynamically, when it is required, by a permissioning adapter. See The 'mapsuffix' parameter.

Multiple instances of the same parameter are not allowed, with the exception of the sort parameter, which from Refiner 7 may be specified multiple times to construct a multi-column sort. See The 'sort' parameter.

An example Refiner subject is shown below. It requests the /CTR/FI/ALL container, sorted and grouped by the Description field.

The filter parameter comprises one or more field-matching criteria.

A single field-matching criterion has the following syntax:

You can join multiple field-matching criteria with logical AND ('&') and logical OR ('|'). There’s no implicit precedence between the logical operators, so you need to establish precedence using parenthesis ('(' and ')').

If the field name or comparison value in a filter criterion includes a Refiner comparison operator (see table above), a Refiner logical operator ('&' or '|'), or the Refiner parameter separator (';'), then these characters must be encoded using a Refiner escape sequence. See Special characters.

The sort parameter comprises a field name, a field data type, and a sort order:

For example, to sort the 'MaturityDate' field in ascending numerical order, use the sort parameter below:

From Refiner 7, you can specify more than one sort parameter in a Refiner parameter string. The sort parameters are applied in the order they are supplied, and create a multi-column sort:

If two or more records have the same value in the sort field(s), the records are sorted into their natural order (the order in which the records' integration adapter would return the records unsorted to the client).

The groupby parameter comprises a single value: the field name to group records by.

Grouping adds extra records to the container that act as headers for blocks of records with the same field value. For example, if you sort the /CTR/FI/All container by the Description field and group the records by the Description field, the returned container looks like this:

Each of the header records (/FILTER/META/CTR/FI/ALL/GROUPHEADER/ and so on) contains one field, SubHeaderText, which contains the value of the field that you are grouping by. When the client application receives the sorted and grouped container, it typically displays the header rows in the grid with different styling to the data rows.

The 'mapsuffix' parameter is added to a Refiner subject dynamically by a permissioning integration adapter.

The parameter comprises a single value:

The suffix is appended to the subjects of the items in the container and is used to implement price tiers. For more information on 'mapsuffix', see Set Refiner user permissions and subject mappings.

The sequence of subscribing to a container, subscribing to all the records in it, and then processing each of the records in Caplin Refiner can take longer than the active request timeout configured in Liberator (see source-request-timeout, add-peer: request-timeout and add-data-service: request-timeout). If Refiner were to wait until it had processed all the results before sending a response, the active request timeout might trigger first and Liberator would then discard the container. To prevent this happening, as soon as Caplin Refiner receives a filter or sort request, it sends back a container response with a single special subject name in it: /FILTER/META/PLACEHOLDER. This is called the container placeholder record. It tells the Liberator that Refiner has received the request, preventing the container subscription from being discarded.