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) on the server.

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 extension functions and operators
• Groovy standard expressions

You can mix and match common expressions, Groovy extension functions and operators and Groovy standard 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

• Expr.containsIgnoreCase(String field, String searchStr)

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

  For example:

Expr.containsIgnoreCase(EXCHANGE_NAME, 'oves')

• Expr.containsWordsStartingWithIgnoreCase(String field, String searchStr, Character delimiter = ' ')

  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
• DateTime as Date: yyyy-MM-dd

The allowed Long date-time representation is epoch time in milliseconds (UTC).

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

Groovy extension functions and operators (since 8.9)

The platform provides a set of extension methods over the base Groovy capabilities to improve developer experience and increase usability.

String extension functions

The String common expressions are also provided using extension functions. The syntax is the following:

• String.containsIgnoreCase(String searchStr)

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

  For example:

EXCHANGE_NAME.containsIgnoreCase('oves')

• String.containsWordsStartingWithIgnoreCase(String searchStr, Character delimiter = ' ')

  This returns true when the field contains a word that begins with the specified string. Casing is ignored. The default delimiter is a whitespace character, but an optional second 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:

DESCRIPTION.containsWordsStartingWithIgnoreCase('desc')

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

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

Date and DateTime extension functions

The Date and DateTime common expressions can be also used as extension functions/operators. The supported date format for String and Long fields remains the same.

The syntax is:

Functions

• String.dateIsToday()
• Long.dateIsToday()
• DateTime.dateIsToday()

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

For example:

TRADE_DATE.dateIsToday()

Operators

String and Long fields can be compared against DateTime values using the standard Java/Groovy comparators: <, <=, ==, !=, >=, and >.

Similarly, DateTime fields can be compared directlyagainst String and Long values.

To illustrate this, here are a few examples using a TRADE_DATETIME field with DateTime type.

For all the examples, the following information applies:

• TRADE_DATETIME represents "1st January 2012 at 00:00".
• 1325376000000 is the epoch time in milliseconds UTC value to represent "1st January 2012 at 00:00".
• The String format used is ISO8601 "yyyy-MM-dd", but other formats are accepted.

Criteria match (epoch time)	Criteria Match (String format)	Result
TRADE_DATETIME == 1325376000000	TRADE_DATETIME == '2012-01-01'	true
TRADE_DATETIME != 1325376000000	TRADE_DATETIME != '2012-01-01'	false
TRADE_DATETIME >= 1325376000000	TRADE_DATETIME >= '2012-01-01'	true
TRADE_DATETIME <= 1325376000000	TRADE_DATETIME <= '2012-01-01'	true
TRADE_DATETIME > 1325376000000	TRADE_DATETIME < '2012-01-01'	false
TRADE_DATETIME < 1325376000000	TRADE_DATETIME > '2012-01-01'	false

If TRADE_DATETIME is set to "1st January 2024 at 00:00", the results will be:

Criteria match (epoch time)	Criteria Match (String format)	Result
TRADE_DATETIME == 1325376000000	TRADE_DATETIME == '2012-01-01'	false
TRADE_DATETIME != 1325376000000	TRADE_DATETIME != '2012-01-01'	true
TRADE_DATETIME >= 1325376000000	TRADE_DATETIME >= '2012-01-01'	true
TRADE_DATETIME <= 1325376000000	TRADE_DATETIME <= '2012-01-01'	false
TRADE_DATETIME > 1325376000000	TRADE_DATETIME < '2012-01-01'	true
TRADE_DATETIME < 1325376000000	TRADE_DATETIME > '2012-01-01'	false

You can, of course, place the epoch time value or the date in String format as the left operand of the expression. For example:

1325376000000 == TRADE_DATETIME

or

'2012-01-01' == TRADE_DATE 

important

DateTime and epoch time UTC comparisons ensure that Data Server queries attempt to match the corresponding Data Server indices (if available) to improve query performance. Therefore, this type of comparison is the recommended approach for all DateTime related queries.

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, you must ensure that QUANTITY > 250 || QUANTITY < 350 is enclosed 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')

You can find the methods for each field type in the Javadoc documentation. For example:

• String
• Long
• Integer
• Short
• Double
• BigDecimal
• Boolean
• DateTime

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.