AdapTable Version:

Framework:

Reducing Expression Complexity

Summary

AdapTable allows developers to reduce the AdapTableQL functionality on offer to users
This is often the case if you are evaluating Expressions yourself externally instead of using AdapTableQL
In particular 2 features are provided:
- Make some Expression Functions unavailable in the Expression Editor and for AdapTableQL evaluation
- Specify that certain Columns cannot be included in Expressions

AdapTable provides a couple of helpful features to reduce the complexity of the Expressions available to users.

Hint

This is particularly useful if you are evaluating Expressions on the Server using your own translation

Limiting Available AdapTableQL Functions

By default all Expression Functions are available in the Expression Editor and available for the AdapTableQL evaluation engine.

Multiple properties in Expression Options can be used to limit the functions which the user can access.

Note

Similarly developers can limit which Predicates are available in Filters

These can be divided into 2 groups:

Limit by Function Type
Limit by Module

Limit By Function Type

To limit Expressions globally for each distinct Function Expression Type use:

systemBooleanFunctions
systemScalarFunctions
systemObservableFunctions
systemAggregatedBooleanFunctions
systemAggregatedScalarFunctions

Deep Dive

How to limit provided Expression Functions

Each property has to be evaluated to a list of Expression Type specific function names:

either directly by defining a list of functions
or by defining a function callback which, using the provided context, evaluates to a list of functionss

For instance to omit 3 Boolean Functions and 1 Scalar Function you would do:

import {Adaptable, AdaptableQL } from '@adaptabletools/adaptable';

  expressionOptions:{
    systemBooleanFunctions: AdaptableQL.BooleanFunctions.filter(
            (functionName) => functionName !== 'BETWEEN' && functionName !== 'NOT' && functionName !== 'CONTAINS'
    ),
    systemScalarFunctions: (context: GlobalExpressionFunctionsContext<ScalarFunctionName>) =>
            context.availableExpressionFunctionNames.filter((functionName) => functionName !== 'ADD'),
};

Hint

All System functions are available through the publicly exported AdaptableQL constant or in the callback context

systemBooleanFunctions

BooleanFunctionName[]

Which Boolean Expression Functions are available

BooleanFunctionName[]

Specifies which Boolean Expression Functions can be used in AdapTableQL and be available in the Expression Editor.

The values listed should be of type BooleanFunctionName:

// Omit 3 Boolean Functions
expressionOptions:{
  systemBooleanFunctions: AdaptableQL.BooleanFunctions.filter(
          (functionName) => functionName !== 'BETWEEN' && functionName !== 'NOT' && functionName !== 'CONTAINS'
  ),
  // OR, ALTERNATIVELY
  systemBooleanFunctions: (context: GlobalExpressionFunctionsContext<BooleanFunctionName>) =>
          context.availableExpressionFunctionNames.filter(
                  (functionName) => functionName !== 'BETWEEN' && functionName !== 'NOT' && functionName !== 'CONTAINS'
          ),
};

systemScalarFunctions

ScalarFunctionName[]

Which Scalar Expression Functions are available

ScalarFunctionName[]

Specifies which Scalar Expression Functions can be used in AdapTableQL and be available in the Expression Editor.

The values listed should be of type ScalarFunctionName:

// Omit 3 Scalar Functions
expressionOptions:{
  systemScalarFunctions: AdaptableQL.ScalarFunctions.filter(
    (functionName) => functionName !== 'ADD' && functionName !== 'MIN' && functionName !== 'MAX'
  ),
  // OR, ALTERNATIVELY
  systemScalarFunctions: (context: GlobalExpressionFunctionsContext<ScalarFunctionName>) =>
    context.availableExpressionFunctionNames.filter(
      (functionName) => functionName !== 'ADD' && functionName !== 'MIN' && functionName !== 'MAX'
    ),
};

systemObservableFunctions

ObservableFunctionName[]

Which Observable Expression Functions are available

ObservableFunctionName[]

Specifies which Observable Expression Functions can be used in AdapTableQL and be available in the Expression Editor.

The values listed should be of type ObservableFunctionName:

// Omit the WHERE Observable Function
expressionOptions:{
  systemScalarFunctions: AdaptableQL.ObservableFunctions.filter(
    (functionName) => functionName !== 'WHERE'
  ),
  // OR, ALTERNATIVELY
  systemScalarFunctions: (context: GlobalExpressionFunctionsContext<ObservableFunctionName>) =>
    context.availableExpressionFunctionNames.filter(
      (functionName) => functionName !== 'WHERE'
    ),
};

systemAggregatedBooleanFunctions

AggregatedBooleanFunctionName[]

Which Aggregated Boolean Expression Functions are available

AggregatedBooleanFunctionName[]

Specifies which Aggregated Boolean Expression Functions can be used in AdapTableQL and be available in the Expression Editor.

The values listed should be of type AggregatedBooleanFunctionName[]:

// Omit the AVG Aggregated Boolean Function
expressionOptions:{
  systemAggregatedBooleanFunctions: AdaptableQL.AggregatedBooleanFunctions.filter(
    (functionName) => functionName !== 'AVG'
  ),
  // OR, ALTERNATIVELY
  systemAggregatedBooleanFunctions: (context: GlobalExpressionFunctionsContext<AggregatedBooleanFunctionName>) =>
    context.availableExpressionFunctionNames.filter(
      (functionName) => functionName !== 'AVG'
    ),
};

systemAggregatedScalarFunctions

AggregatedScalarFunctionName[]

Which Aggregated Scalar Expression Functions are available

AggregatedScalarFunctionName[]

Specifies which Aggregated Scalar Expression Functions can be used in AdapTableQL and be available in the Expression Editor.

The values listed should be of type AggregatedScalarFunctionName[]:

// Omit the MIN & MAX Observable Functions
expressionOptions:{
  systemAggregatedBooleanFunctions: AdaptableQL.AggregatedScalarFunctions.filter(
    (functionName) => functionName !== 'MIN' && functionName !== 'MAX'
  ),
  // OR, ALTERNATIVELY
  systemAggregatedBooleanFunctions: (context: GlobalExpressionFunctionsContext<AggregatedScalarFunctionName>) =>
    context.availableExpressionFunctionNames.filter(
      (functionName) => functionName !== 'MIN' && functionName !== 'MAX'
    ),
};

Limit By Module

To limit Expressions on a per Module basis use moduleExpressionFunctions in Expression Options.

moduleExpressionFunctions

ModuleExpressionFunctions

Which Expressions Functions are available - specified by Module

ModuleExpressionFunctions

This property specifies which AdapTableQL Expression Functions are available in Adaptable on a per Module basis.

The property is defined as follows:

  moduleExpressionFunctions?:
    | ModuleExpressionFunctionsMap
    | ((context: ModuleExpressionFunctionsContext) => ModuleExpressionFunctions | undefined);

As can be seen the property can be evaluated in one of 2 ways:

Directly returning a Map

This approach returns a ModuleExpressionFunctionsMap.

This is a Record with the Adaptable Modules as property keys and the specific Expression Functions as property values

Via a function

The function receives a ModuleExpressionFunctionsContext property and returns the ModuleExpressionFunctions

The ModuleExpressionFunctionsContext property is defined as follows:

Property	Description
availableAggregatedBooleanFunctionNames	The global aggregated boolean expression functions
availableAggregatedScalarFunctionNames	The global aggregated scalar expression functions
availableBooleanFunctionNames	The global boolean expression functions
availableObservableFunctionNames	The global observable expression functions
availableScalarFunctionNames	The global scalar expression functions
module	The Adaptable Module requesting the expression functions
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Exclude observable functions 'ROW_CHANGE' from Alert Module
// and exclude scalar functions 'LOWER' and 'UPPER' from Calculated Column
// add custom scalar function LATEST_PRICE to Calculated Column
expressionOptions:{
  moduleExpressionFunctions: (context: ModuleExpressionFunctionsContext) => {
    if (context.module === 'Alert') {
      return {
        systemObservableFunctions: context.availableObservableFunctionNames.filter(
                (functionName) => functionName !== 'ROW_CHANGE'
        )
      };
    }
    if (context.module === 'CalculatedColumn') {
      return {
        systemScalarFunctions: context.availableScalarFunctionNames.filter(
                (functionName) => functionName !== 'LOWER' && functionName !== 'UPPER'
        ),
        customScalarFunctions: {
          LATEST_PRICE: {
            handler(args, context) {
              const tradeStatus = context.node.data['tradeStatus'];
              return tradeStatus == 'active'
                      ? priceService.getLatestPrice(args[0])
                      : context.node.data['closingPrice'];
            },
            description: 'Returns latest price for an Instrument from a Server',
            signatures: ['LATEST_PRICE(instrument: string)'],
            examples: ['LATEST_PRICE([ticker])'],
          },
        }
      };
    }
  },
};

Note

Functions defined in moduleExpressionFunctions inherit & override functions defined globally in systemXFunctions
e.g. if the Alert module only provides customised systemObservableFunctions, it inherits all other system functions (systemBooleanFunctions, systemScalarFunctions, etc.)

AdapTableQL: Limiting Functions

Fork Fork

Expand to see the Expressions removed

expressionOptions: {
  // globally defined functions
  systemScalarFunctions: (
    context: GlobalExpressionFunctionsContext<ScalarFunctionName>
  ) =>
    context.availableExpressionFunctionNames.filter(
      functionName => functionName !== 'ADD'
    ),
  // module specific functions  
  moduleExpressionFunctions: (
    context: ModuleExpressionFunctionsContext
  ) => {
    if (context.module === 'CalculatedColumn') {
      return {
        // the `availableScalarFunctionNames` are the ones defined above, in `expressionOptions.systemScalarFunctions`
        systemScalarFunctions: context.availableScalarFunctionNames.filter(
          functionName =>
            functionName !== 'LOWER' && functionName !== 'UPPER'
        ),
      };
    }
    // ALL other modules will inherit the functions defined globally
  },
  },

Limiting Queryable Columns

By default all Columns in AdapTable can be used in a Query.

To specify whether or not a given column is Queryable, provide an implementation for the isColumnQueryable property of Expression Options.

isColumnQueryable

Default: true

Boolean

Whether a Column should be included in AdapTableQL Expressions

Custom function which specifies if a Column should be included in AdapTableQL Expressions.

Hint

This is often used in conjunction with the Server-Side Row Model to reduce the complexity of an Expression

The function receives a QueryableColumnContext object (which simply contains the Column) and returns a boolean:

Caution

If you want all columns in the Grid to be available, do not provide an implementation for this function

// Don't allow Date columns to be queryable
  expressionOptions:{
    isColumnQueryable: (queryableColumnContext: QueryableColumnContext) => { 
      return queryableColumnContext.adaptableColumn.dataType != 'date' 
    },
};

Note

If no implementation is provided, all Columns can be used in Expressions

Hint

Use filter and floatingFilter properties in GridOptions to set which Columns can be filtered

AdapTableQL: Limiting Columns

Fork Fork

In this example we have provided an implementation for the isColumnQueryable property to prevent these columns from being used in Expressions:
- The License Column
- All Date Columns

Expand to see how Queryable Columns were set

expressionOptions: {
  isColumnQueryable: (queryableColumnContext: QueryableColumnContext) => {
    return (
      queryableColumnContext.adaptableColumn.dataType != 'date' &&
      queryableColumnContext.adaptableColumn.columnId != 'license'
    );
  },
},

Try It Out

Open the Expression Editor (e.g. by clicking the arrows in the Query toolbar) and note that License and all Date Columns are absent from the Column list

PreviousFIELD Function NextRelative Change Expressions

Framework: