Evaluating Expressions via the API

AdapTable typically evaluates an Expression in response to an event in the UI.

For example when running a Grid Filter, calculating a Calculated Column value, or rendering a Cell with a Conditional Style, AdapTable will hand over the evaluation to AdapTableQL which will return the result.

However it is possible to leverage AdapTableQL programmatically - to evaluate an Expression entirely via the API.

const result = adaptableApi.expressionApi.evaluateStandardExpression({
  expression: '[price] * [qty] > 1000',
  primaryKeyValue: 42,
});

if (result.success) {
  console.log(result.value); // true | false
} else {
  console.warn(result.errorMessage);
}

Why evaluate via API

There are many potential use cases where you might want to evaluate an Expression using the API.

For instance you might want to:

• ask a question once (“does this row pass?”, “what is this value?”) outside of a Module
• drive your own UI — a toolbar button or custom form — from an Expression the user typed or you shipped
• run a what-if: would this row still match if price were 120?
• filter your own array of rows, not the grid

API Methods

AdapTable provides 4 Expression-evaluation methods in Expression API:

• evaluateStandardExpression
• evaluateAggregatedExpression
• filterRowNodes
• filterDataSet

These are designed to be able to meet a range of potential use cases:

evaluateStandardExpression

Use this function to evaluate a Standard Expression against a single row.

The Expression determines the return value: a boolean condition will yields true / false, while a value Expression will yield that value.

evaluateStandardExpression(
  request: EvaluateStandardExpressionRequest
): ExpressionEvaluationResult<unknown>;

adaptableApi.expressionApi.evaluateStandardExpression({
  expression: '[price] * 1.19',
  rowNode,
});

adaptableApi.expressionApi.evaluateStandardExpression({
  expression: "[make] = 'Toyota'",
  data: {make: 'Toyota', price: 350},
});

// Would this row pass if price became 120?
adaptableApi.expressionApi.evaluateStandardExpression({
  expression: '[price] > 100',
  primaryKeyValue: 42,
  cellValueOverride: {columnId: 'price', value: 120},
});

evaluateAggregatedExpression

Use this function to evaluate an Aggregation Expression over a set of rows (the grid, a narrowed subset, or an array you supply).

It returns a snapshot of the result — the aggregated value, any GROUP_BY breakdown, and a per-row projection.

When the Expression is a condition, you also get whether it matches.

evaluateAggregatedExpression(
  request: EvaluateAggregatedExpressionRequest
): ExpressionEvaluationResult<AggregatedExpressionEvaluationValue>;

adaptableApi.expressionApi.evaluateAggregatedExpression({
  expression: 'AVG{[price]}',
  rowScope: 'visible',
  rowFilter: rowNode => rowNode.data.region === 'EMEA',
});

const snapshot = adaptableApi.expressionApi.evaluateAggregatedExpression({
  expression: 'SUM{[price], GROUP_BY([make])}',
  dataSet: myRows,
});

const limit = adaptableApi.expressionApi.evaluateAggregatedExpression({
  expression: "SUM{[PnL]} > '5M'",
});
if (limit.success && limit.value.matches) {
  // the SUM breached — limit.value.value is the SUM itself
}

Observable Expressions

There is no API method to subscribe to an Observable Expression.

To react live to an Observable pattern, create an Observable Alert and listen to the Alert Fired Event, or display the value in an Observable Calculated Column.

filterRowNodes

Use this function to return the grid rows that match a boolean Expression.

It evaluates the Expression once per row and returns the matching IRowNodes in source order.

filterRowNodes(
  request: FilterRowNodesRequest
): ExpressionEvaluationResult<IRowNode[]>;

const emea = adaptableApi.expressionApi.filterRowNodes({
  expression: '[region] = "EMEA" AND [notional] > 1000000',
  rowScope: 'visible',
});

filterDataSet

Use this function to filter an array of your own rows with a boolean Expression.

Same behaviour as filterRowNodes, but the input and output are your objects rather than grid row nodes.

filterDataSet(
  request: FilterDataSetRequest
): ExpressionEvaluationResult<Record<string, unknown>[]>;

const matching = adaptableApi.expressionApi.filterDataSet({
  expression: '[price] > 100',
  dataSet: myRows,
});

The rest of ExpressionApi is supporting: isValid* before you evaluate, getColumnsFromExpression, getASTForExpression (also used by Server Evaluation).

Function Results

Synchronous evaluate / filter methods never throw for expected input errors (typos, unknown columns, missing row, unavailable functions).

type ExpressionEvaluationResult<T> =
  | {success: true; value: T}
  | {success: false; errorMessage: string};

Always check success before reading value.

The Expression decides what value is.

A condition such as [price] > 100 yields true / false. [price] * 1.19 yields a number.

adaptableApi.expressionApi.evaluateStandardExpression({
  expression: "[region] = 'EMEA'",
  data: {price: 100, region: 'EMEA'},
  columns: [{columnId: 'region', dataType: 'text'}],
});