Guide to Expressions in AdapTableQL

AdapTableQL is a powerful, home-grown, Query Language designed by the AdapTable Tools team.

AdapTableQL includes a powerful rules engine used for evaluating live data.

Expressions

At the heart of AdapTableQL are Expressions - a very powerful querying construct which:

• Can contain numerous functions, conditions and arguments
• Are typically evaluated against whole rows of AG Grid data
• Can support multiple return types
• Includes reactive(observable), aggregated or cumulated expressions
• Are designed to be fully human-readable and can be written entirely by hand

There are 3 main types of Expressions provided by AdapTableQL:

Standard

A Standard Expression is evaluated against each row in isolation and returns a single value.

The return value can be of 2 return types:

• any data type - used in the Calculated Column Module
• boolean data type - used when a true / false condition needs to be evaluated, e.g. Grid Filter Module only displays rows, and Conditional Styling only styles rows, where the evaluated Expression returns true.

Aggregated

Aggregated Expressions are run against aggregated data; each value is dynamically derived by aggregating multiple rows and columns of the grid. There are 4 types of Aggregated Expression :

• Aggregated Scalar - return value of any data type and available when creating Calculated Columns.
• Aggregated Boolean Expressions: return true / false currently used in the Alerts Module.

• Cumulative Expressions - Perform Cumulative Aggregations

• Quantile Expressions - Create 'buckets' of values

Observable (Rx)

Observable Expressions use advanced reactive techniques (Rx) to watch for changes (or lack of changes) in data that match a particular pattern.

When the expression evaluates to TRUE, AdapTable can perform a specified action.

Expression Modules

AdapTable users are able to use Expressions in numerous Modules.

Expression Functions

An Expression will include (potentially multiple) Expression Functions.

These are useful functions that are shipped with AdapTableQL which cover a multitude of use cases.

There are 3 types of Expression function available in AdapTableQl - in line with the 3 types of Expressions:

For example this Standard Expression contains 3 Expression Functions:

 STARTS_WITH([col1], 'ABC') OR MIN([col2], [col3]) > 100

• STARTS_WITH Boolean Expression Function
• OR Logical Function
• MIN Scalar Expression Function

Advanced Expression Functions

AdapTableQL provides some "specialised" Functions for particular, advanced use cases:

• QUERY Function - enables referencing Named Queries in other Expressions

• VAR Function - allows developers to provide values which will be evaluated in other Expressions
• CASE and Ternary Operators - enable logic to be used inside Expressions

Writing Expressions

Expressions are designed to be hand-written and human readable. An Expression can include many different elements including:

• Expression Functions
• Operators
• Columns
• Hard coded values

UI Components

AdapTableQL is designed to be used at run time by end users with no technical expertise.

AdapTable provides 2 very useful UI Components designed to add easy creation of Expressions:

• Query Builder enables (Boolean) Expressions to be created purely via UI controls

• Expression Editor used to hand-write Expressions (and for more complicated scenarios), and contains many useful features including functions list, context help and validation

Configuring Expressions

Many elements in AdapTableQL can be configured using properties in Expression Options.

In particular developers are able to:

• add Custom Expression Functions
• ensure that some Expression Functions are unavailable (both to end-users or to AdapTableQL)
• reduce complexity - useful when evaluating expressions externally
• configure case sensitivity

Custom AdapTableQL Functions

Developers can provide their own custom built ExpressionFunctions in Expression Options.

Once provided, these Expressions will be available in the Expression Editor and invoked by AdapTableQL when the Expression is being evaluated.

Reducing Expression Complexity

By default, all System Expression Functions are available to end users, and can be used against all columns.

However sometimes developers might wish to reduce the AdapTableQL functionality on offer.

In this scenario, AdapTable provides 2 features to help developers - namely:

• Remove some AdapTableQL functions (either globally or on a per-module basis), so they are not available in the Expression Editor

• Specify that certain Columns cannot be queried or included in Expressions

Evaluating Expressions Externally

Generally there is no need for developers to understand how AdapTableQL works; merely to ensure that it is provided with valid input.

However, occasionally you might want to perform some querying externally (e.g. on your Server).

This is possible and requires 3 steps:

1. In Expression Options specify which modules should be evaluated externally (instead of AdapTableQL)
2. Listen to the Grid Filter Applied Event to know when Queries need to run
3. Perform the Query yourself and return the data to Adaptable

Case Sensitivity

By default Expressions are case insensitive but this can be changed if required, by setting the caseSensitiveExpressions flag to true.

// Enforce case sensitivity in AdapTable QL for string evaluations
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    caseSensitiveExpressions: true
  }
}