Skip to main content

Criteria matching

This page looks at how you can apply criteria matching when you connect to real-time queries (Data Server) and Snapshot queries (Request Server) resources.

When you make a request to a resource, you can use criteria matching to filter the data returned. This can take the form of:

  • Common expressions
  • Groovy expressions

You can mix and match common expressions and custom groovy expressions using the && (logical AND) and || (logical OR) boolean operators. This is explained in more detail below.

All expressions must return a boolean value (true or false).

info

When you make a request to a Request Server resource, you specify the filtering in the request message.

When you connect to a Data Server resource, the attributes you specify for filtering are automatically included in the DATA_LOGON message that is sent to the server when the connection is first established.

Common expressions​

The platform provides common expressions that are especially helpful for Date and DateTime filtering. Common expressions are called using the Expr binding and take one or two parameters:

  • The first parameter is always a query field. In the case of date/datetime, this can either represent the epoch time in milliseconds or a String value representing the actual Date and DateTime in the supported formats.
  • The second parameter (if applicable) is a predefined String value

String operations​

  • containsIgnoreCase(String, String)

    This returns true when our field contains the string. Casing is ignored.

    For example:

Expr.containsIgnoreCase(EXCHANGE_NAME, 'oves')`

  • containsWordsStartingWithIgnoreCase(String, String)

    This returns true when the field contains a word with the string. Casing is ignored. The default delimiter is a whitespace character, but a third parameter can be passed to specify a different delimiter.

    For example, if the DESCRIPTION field contains the value "This is a description", the following containsWordStartingWithIgnoreCase expression will return true:

Expr.containsWordsStartingWithIgnoreCase(DESCRIPTION, 'desc')

And in this next example, if the ORDER_TYPE field contains the value "GTC,OCO", the following expression will return true:

Expr.containsWordsStartingWithIgnoreCase(ORDER_TYPE, 'OCO', ',')`

Date operations​

The allowed String formats are:

  • DateTime with milliseconds precision: yyyyMMdd-HH:mm:ss.SSS
  • DateTime with seconds precision: yyyyMMdd-HH:mm:ss
  • DateTime with minutes precision: yyyyMMdd-HH:mm
  • DateTime as Date: yyyyMMdd

The following operations are available:

  • dateIsBefore(date as DateTime|String|Long, String)

    This returns true when the date in the given field is before the date specified.

    For example:

Expr.dateIsBefore(TRADE_DATE,'20150518')`

  • dateIsAfter(date as DateTime|String|Long, String)

    This returns true when the date in the given field is after the date specified.

    For example:

Expr.dateIsAfter(TRADE_DATE,'20150518')`

  • dateIsGreaterEqual(date as DateTime|String|Long, String)

    This returns true when the date in the given field is greater or equal to the date specified.

    For example:

Expr.dateIsGreaterEqual(TRADE_DATE,'20150518')

  • dateIsLessEqual(date as DateTime|String|Long, String)

    This returns true when the date in the given field is less or equal to the date specified.

    For example:

Expr.dateIsLessEqual(TRADE_DATE,'20150518')

  • dateIsEqual(date as DateTime|String|Long, String)

    This returns true when the date in the given field is equal to the date specified.

    For example:

`Expr.dateIsEqual(TRADE_DATE,'20150518')`

  • dateIsToday(date as DateTime|String|Long)

    This returns true when the data in the given field is equal to today's date (using system local time).

    For example:

Expr.dateIsToday(TRADE_DATE)`

DateTime operations​

  • dateTimeIsBefore(datetime as DateTime|String|Long, String)

    This returns true when the datetime in the given field is before the datetime specified.

    For example:

Expr.dateTimeIsBefore(TRADE_DATETIME,'20150518-10:50:24')`

  • dateTimeIsAfter(datetime as DateTime|String|Long, String)

    This returns true when the datetime in the given field is after the datetime specified.

    For example:

Expr.dateTimeIsAfter(TRADE_DATETIME,'20150518-10:50:24')

  • dateTimeIsGreaterEqual(datetime as DateTime|String|Long, String)

    This returns true when the datetime in the given field is greater or equal to the datetime specified.

    For example:

Expr.dateTimeIsGreaterEqual(TRADE_DATETIME,'20150518-10:50:24')`

  • dateTimeIsLessEqual(datetime as DateTime|String|Long, String)

    This returns true when the datetime in the given field is less or equal to the datetime specified.

    For example:

Expr.dateTimeIsLessEqual(TRADE_DATETIME,'20150518-10:50:24')

Groovy expressions​

Groovy expressions provide the most flexibility when you are applying filtering at the front end. They enable you to use complex boolean logic to filter your fields using Java syntax.

Note - You can not filter over derived fields.

Below are a few examples of valid Groovy expressions.

// Quantity is more than 10000
QUANTITY > 10000

// Quantity is more than or equal to 10000
QUANTITY >= 10000

// Quantity is less than 10000
QUANTITY < 10000

// Quantity is less than or equal to 10000
QUANTITY <= 10000

// Quantity is equal to 10000
QUANTITY == 10000

// Quantity is not equal 10000
QUANTITY != 10000

You can also join multiple expressions together. These expressions can even be the common expressions mentioned above.

// Quantity is more than 100 AND less than 500
QUANTITY > 100 && QUANTITY < 500

// Quantity is less than 100 OR more than or equal to 500
QUANTITY < 100 || QUANTITY >= 500

// Date is today AND QUANTITY is more than 100
Expr.dateIsToday(TRADE_DATE) && QUANTITY > 100

Advanced boolean logic​

If you use logical OR in your filter, you lose the ability to use indexing for searches. If you want to use more advanced boolean logic, you can pass brackets to ensure that each part of your filter is checked in line with your business needs.

The following complex example defines:

  • If the date is today, the QUANTITY must be over 100
  • If the date is 1st of April 2022, the QUANTITY must be between 250 and 350
(Expr.dateIsToday(TRADE_DATE) && QUANTITY > 100) || (Expr.dateIsEqual(TRADE_DATE, "20220401") && (QUANTITY > 250 || QUANTITY < 350))

In Java's operator precedence, logical AND is evaluated before logical OR. For this reason, we must add QUANTITY > 250 || QUANTITY < 350 within brackets.

Object methods​

You can also use the Java methods that correspond to each field type to build criteria. For example, if you are using a DESCRIPTION field with type STRING, you can write the following expression to check if the content starts with the string 'This':

DESCRIPTION.startsWith('This')

The methods available for each of the field types can be found in their Javadoc documentation. For example:

Streaming data​

The Data Server is your source of streaming data. It provides a set of queries, each of which serves some or all fields from a specific table or view. These are your resources (along with the resources in the Request Server and the Event Handler). You need to know which queries are available to you, and more importantly, exactly what is available in each query.

When you request streaming data for an element, such as a Grid Pro, the platform sends a DATA_LOGON message that includes any attributes you have defined for the element (such as max-rows and max-view). These attributes enable you to limit the number of rows returned, for example.

The platform creates the DATA_LOGON message automatically; you can view the details in our section on the Data Server.

You can apply filtering at the front end to control the data returned by the Data Server query. These filters are also automatically included in the DATA_LOGON message.