AdapTable Version:

Framework:

Evaluating Expressions & Predicates Externally

Summary

By default, Expressions and Predicates are evaluated automatically by AdapTable on the Client
However sometimes you might wish to peform the evaluation yourself on the server
AdapTable facilitates this for you by:
- allowing you to choose which Modules (or Expressions) will evaluate on the Server or Client
- firing Events to give you oversight of what needs evaluation
- providing you with the AST that is used by AdapTableQL when managing Expressions

Expression and Predicate evaluation by AdapTable is generally abstracted away.

End users create Predicates and Expressions at run-time - either in the UI using Wizards or the Expression Editor - or provide them at design-time in Initial Adaptable State, and everything "just works".

But some developers have a more complicated 2-step use case:

run-time users will build Predicates and Expressions
but the developer team will perform the actual evaluation themselves on their Server

Caution

This should not be confused with using the Server-Side Row Model which forces server evaluation

This page provides some tips and tricks to help achieve this.

Specifying Externally Evaluated Modules

The first, key, step is to tell AdapTable which Modules (or Expressions) should be evaluated externally.

Note

Four Modules can be evaluated externally: Alerts, Calculated Columns, Column Filters and Grid Filter

This is done via the evaluateAdaptableQLExternally property in Expression Options.

Hint

This allows you to control when Server evaluation will take place
e.g. you can evaluate the Grid Filter remotely but let AdapTable manage Calculated Columns and Column Filters

It is in the form of a function which receives context about the Expression / Module and returns a boolean.

Caution

This is only required when using AG Grid's Client-Side Row Model
If using the Server-Side Row Model then all filtering (and sorting) is automatically ignored on the client

evaluateAdaptableQLExternally

Default: false

Boolean

Whether a Module (or a specific Expression / Predicate) should be evaluated externally

By default AdapTable will perform all evaluations of Predicates and Expressions

However you might prefer to evaluate a particular Module (e.g. Column Filters) externally (i.e. yourselves).

Use this property to tell AdapTable which Modules (or Expressions) should not be evaluated by AdapTable.

It is in the form of a function which receives context about the expression / module and returns a boolean.

The context is of type EvaluateExpressionExternallyContext and is defined as follows:

Property	Description
expression	Expression to evaluate
module	Module being evaluated: Alert, CalculatedColumn, ColumnFilter, GridFilter
object	AdapTable Object which contains the Expression or Predicates
predicates	Any Predicates to evaluate
referencedColumns	Columns contained in Expression
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

The module property is of type AdaptableQLModule which can be of one of 4 values:

Alert - runs Alerts externally
CalculatedColumn - returns default value for the Calculated Column so value can be provided externally
ColumnFilter - evaluates Column Filters externally
GridFilter - evaluates the Grid Filter externally

Hint

Leave this property undefined to maintain the default behaviour of AdapTableQL handling all evaluations

// Evaluate Columns Filters, Alerts & Calculated Columns in AdapTableQL
// But evaluate the Grid Filter externally
expressionOptions = {
  evaluateAdaptableQLExternally: (context: EvaluateExpressionExternallyContext) => {
    return context.module === 'GridFilter';
  },
},

In more advanced use cases you can use the Context object to make a per-instance decision as it contains:

the actual Adaptable Object being evaluated
an expression property containing the Expression being evaluated
a predicates property containing the Predicates being evaluated

// Evaluate Expressions on the Server which use the MY_EXTERNAL_FUNCTION expression function
expressionOptions = {
  evaluateAdaptableQLExternally: (context: EvaluateExpressionExternallyContext) => {
    return context.expression.includes('MY_EXTERNAL_FUNCTION')
  },
},

Turning off Automatic Validation

By default, AdapTableQL will validate Expressions automatically as they are being written.

If you are evaluating the Grid Filter on your server you might wish to set performExpressionValidation in Expression Options to false to avoid false positives.

performExpressionValidation

Default: true

Boolean

Validate Expressions before they can be run or saved

By default AdaptablQL will validate all Expressions in the AdaptableUI before they can be run or saved.

This is generally the preferred behaviour to avoid confusion.

However sometimes, particularly if evaluation Expressions remotely, this can be intrusive and not helpful.

Simply set the property to false and AdapTable will permit Expressions it cannot understand to run regardless:

// Don't allow AdapTableQL to validate Expressions
expressionOptions = {
  expressionOptions: {
    performExpressionValidation: false,
  },
};

Reducing Expression Complexity

Expressions are very rich and powerful, and potentially extremely complex.

When running on the Client that complexity is not problematic as AdapTable takes care of all evaluations.

However if evaluating the Grid Filter (or Calculated Columns) on the server it means a lot of work is required.

AdapTable helps you by allowing you to reduce the compexity of the Expressions in 2 ways:

Limiting which functions are available in Expressions
Limiting which columns can be included in Expressions or can be filtered

Find Out More

See Reducing Expression Complexity for more information
Consult Managing System Predicates for instructions on limiting which predicates are available in Column Filters

AdapTable Events

As noted above, AdapTable will not evaluate any Modules for which the evaluateAdaptableQLExternally function returns false.

Instead developers should subscribe to Adaptable Events designed for this purpose.

Note

This allows developers to perform their own external evaluation as required

The results of the external evaluation will then need to be returned to AdapTable and displayed accordingly.

Hint

There are many methods in Grid API which can be used to supply data to AdapTable
The most commmonly used is setGridData (see Managing Grid Data for more information)

AdapTable will automatically populate AG Grid with any data with which it is provided.

It will also take care or re-applying all column sorts and column formats as required.

The 3 most relevant Adaptable Events are:

Grid Filter Applied

The Grid Filter Applied Event is published any time a Grid Filter runs in AdapTable.

It contains details of the Grid Filter's Expression and the AST used by AdapTableQL to evaluate it.

Column Filter Applied

The Column Filter Applied Event is published each time Column Filters are applied.

Hint

If evaluating Column Filters externally, you can run them all in one batch if preferred
To do this set manuallyApplyColumnFilter in Column Filter Options to true (see Manually Applying Column Filter)

Calculated Column Changed

The Calculated Column Changed Event fires whenever anything changes in Calculated Column State, i.e. if a Calculated Column has been added, edited or deleted.

Using the AST

AdapTable will make the AST it uses when evaulating an Expression available where necessary.

Note

This is available in the Info property provided by the Grid Filter Applied and Calculated Column Changed Events:
- gridFilterExpressionAST property in GridFilterAppliedInfo
- calculatedColumnExpressionAST property in CalculatedColumnChangedInfo

Hint

Any Expression's AST can be retrieved via the getASTForExpression function in the Expression API

AdaptableQL Server Evaluation

Fork Fork

This example demonstrates Server Evaluation using Filters
In the demo we listen to the Column Filter Applied Event to get the latest applied Filters in the Grid
We then call our mock Server which translates the Predicate into SQL - the rough and ready code we used is here - which runs the associated SQL Query
The server then returns the new data to AdapTable, which in turn populates AG Grid with it (using Grid API methods)

Expand to see how Filters are evaluated externally

We tell AdaptableQL not to evaluate Column Filters:

expressionOptions: {
  evaluateAdaptableQLExternally: (
    context: EvaluateExpressionExternallyContext
  ) => { return context.module === 'ColumnFilter' },
},

In the AdaptableReady Event we populate the Grid with initial data:

export const onAdaptableReady = async (info: AdaptableReadyInfo) => {
  const adaptableApi: AdaptableApi = info.adaptableApi;
  const gridOptions = info.gridOptions;
  const startRow = 0;
  const endRow = 1000;

  const response = await fetch(API_BASE, {
    method: 'post',
    body: JSON.stringify({
      startRow,
      endRow,
    }),
    headers: {'Content-Type': 'application/json; charset=utf-8'},
  });
  const {rows} = await response.json();
  adaptableApi.gridApi.loadGridData(rows);
};

And we listen to the Filter Applied Event to run the Filters externally and then repopulate the Grid with the results

adaptableApi.eventApi.on(
  'ColumnFilterApplied',
  async (eventInfo: ColumnFilterAppliedInfo) => {
    const filters = adaptableApi.filterApi.columnFilterApi.getColumnFilterDefs();
    const request = {
      adaptableFilters: filters,
      includeSQL: true,
      startRow,
      endRow,
    };

    gridOptions.api?.showLoadingOverlay();

    const response = await fetch(API_BASE, {
      method: 'post',
      body: JSON.stringify(request),
      headers: {'Content-Type': 'application/json; charset=utf-8'},
    });
    const {rows, sql} = await response.json();
    adaptableApi.gridApi.loadGridData(rows);
    gridOptions.api?.hideOverlay();
  }
);

Try It Out

Run a Column Filter in the Filter Bar and see how the Grid updates
Note how we output the SQL to System Status Toolbar

JSON Translation

All Column Filter and Grid Filter objects (plus Alerts and Calculated Columns) in Adaptable State are JSON.

Caution

This means that in order to perform searching and filtering on the server this JSON will need to be 'translated' into something that the particular server can understand.

Obviously each server is different so AdapTable cannot provide an out of the box implemenation, but we do work with a number of partners who have performed this for clients.

We also have a Grid Gurus consultancy service who can advise you in a bespoke manner.

AdaptableQL Server Evaluation

(Recorded with AdapTable v15.0)

PreviousTechnical Reference

Framework: