# AdapTableQL Expression Technical Reference Canonical page: https://www.adaptabletools.com/docs/technical-reference-expression ## Expression Options | Property | Type | Description | Default | | --- | --- | --- | --- | | [caseSensitiveExpressions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#casesensitiveexpressions) | `boolean` | Perform case-sensitive text comparisons when evaluating Expressions | false | | [customAggregatedFunctions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#customaggregatedfunctions) | `Record \| ((context: `[`GlobalExpressionFunctionsContext`](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionscontext.md)`) => Record)` | Bespoke Aggregated Expression Functions — to complement those provided by
AdapTable (Calculated Column Aggregated / Alert Aggregated).

Omit `category` (or set `'Aggregation'`) to list under the Aggregation
Functions-menu section; any other string creates a section with that name.
Use `isAvailable` with to limit
modules (Alert / Calculated Column only — not Layout Row Summary or Cell
Summary). Toolbar chips still use `expressionEditorButtons`.

The reducer receives `currentValue` as the **computed input** for that
row (the aggregation's input expression, not necessarily a raw column
cell). `aggColumnId` is set only when the input is a bare column ref.
A name registered in both `customStandardFunctions` and this map is a
dual name: `NAME()` is row-wise, `NAME{…}` is the aggregation.
Extra constants are positional `args`; per-row logic is a custom
scalar used as the input.

Every aggregation accepts `GROUP_BY` and `WHERE`. Further clauses are
capabilities the definition declares: `cumulative` (accept
`CUMULATIVE([orderCol])` — a running value per row), `weight` (accept
`WEIGHT([col])`, delivered as `weightValue`) and `returnType` (static
result type for Calculated Column data type / type checks). Declared
capabilities are picked up automatically by validation, the Expression
Editor clause chips, the Cumulative editor and the Query Builder.
`extends` is not supported for aggregations. | undefined (none) | | [customStandardFunctions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#customstandardfunctions) | `Record \| ((context: `[`GlobalExpressionFunctionsContext`](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionscontext.md)`) => Record)` | Bespoke Standard Expression Functions — to complement those provided by
AdapTable. “Standard” matches the Expression Editor (vs Aggregated).

Registers both value-producing functions and boolean predicates. A custom
function is treated as a boolean predicate (usable as a filter or alert
condition) **only** when it declares `returnType: 'boolean'` — predicates
MUST set that property. `returnType` is required; use a value from
`EXPRESSION_RETURN_TYPES` ('boolean' \| 'number' \| 'string' \| 'date' \|
'object' \| 'null' \| 'any').

Set `category` to a value from `EXPRESSION_CATEGORIES` (e.g. `'date'`,
`'general'`, `'custom'`) so the function appears in the matching Expression
Editor menu. Omit `category` (or use `'custom'`) for the Custom menu; any
other string creates a menu with that name.

Entries are **flat** objects combining the AQL evaluation props
(`handler`, `returnType`, `operands`, docs) with the Adaptable
presentation / availability props (`label`, `icon`, `isAvailable`, …) —
see `AdaptableCustomExpressionFunction`. Alternatively an entry may be
an `AdaptableCustomExpressionFunctionWithExtends` partial that inherits
metadata from a system (or previously registered custom) function via
`extends` — useful when overriding a system operator such as `IS_BLANK`
while keeping its label / icon / operands.

Boolean predicates stay Expression-Editor-only unless they declare
`returnType: 'boolean'` and `operands` with arity 1 or 2 (column-only, or
column + value). Optional `label` is used in the operator picker.
`operands` of arity 0 / 3+ do not appear in Query Builder / ColumnFilter.

Toolbar chips are separate: use `expressionEditorButtons` (same as for
system functions). | undefined (none) | | [displayColumnFriendlyNamesForExpressions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#displaycolumnfriendlynamesforexpressions) | `boolean` | Reference a Column's Header (i.e. FriendlyName) in all Expression overviews (instead of ColumnId) | true | | [editorOptions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#editoroptions) | [`ExpressionEditorOptions`](https://www.adaptabletools.com/docs/reference/expressioneditoroptions.md) | Which UI editors are available for Boolean Expressions, and which opens first | | | [evaluateAdaptableQLExternally](https://www.adaptabletools.com/docs/reference/expressionoptions.md#evaluateadaptableqlexternally) | `(context: `[`EvaluateExpressionExternallyContext`](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md)`) => boolean` | Whether a Module (or specific expression) should be evaluated by AdaptableQL | All Modules are evaluated by AdapTable | | [evaluateDatesUsingTime](https://www.adaptabletools.com/docs/reference/expressionoptions.md#evaluatedatesusingtime) | `boolean \| ((context: `[`AdaptableColumnContext`](https://www.adaptabletools.com/docs/reference/adaptablecolumncontext.md)`) => boolean)` | Whether date comparisons use the full timestamp (exact instant) rather than the calendar day.

Affects the `IN` operator on date columns wherever Expressions are evaluated
(Queries, Styled Columns, Alerts, Column Filters, ...): `true` compares the exact
datetime, `false` compares the calendar day. Also controls whether the date Column
Filter's distinct-value tree drills down to individual times.
When an `IN` right-hand value is an ISO string containing `T`, the exact instant is used regardless. | false | | [expressionEditorButtons](https://www.adaptabletools.com/docs/reference/expressionoptions.md#expressioneditorbuttons) | `(context: `[`ExpressionEditorButtonsContext`](https://www.adaptabletools.com/docs/reference/expressioneditorbuttonscontext.md)`) => `[`ExpressionEditorButton`](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md)`[]` | Customise the function/operator chips shown above the Expression Editor.

Called per editor surface with AdapTable's `defaultButtons` for that type.
Return those unchanged to keep defaults, or amend/replace them (useful when
adding chips for `customStandardFunctions` / `customAggregatedFunctions`).

Editor types are intentionally coarse (e.g. `standard` covers both boolean
and scalar editors; `aggregated` covers aggregated scalar and aggregated
boolean) so callers are not forced to treat those as separate concepts.

Only chips whose function is available for the current Module are rendered. | undefined (use AdapTable defaults for each editor type) | | [fields](https://www.adaptabletools.com/docs/reference/expressionoptions.md#fields) | [`AdaptableField`](https://www.adaptabletools.com/docs/reference/adaptablefield.md)`[] \| ((context: `[`AdaptableFieldContext`](https://www.adaptabletools.com/docs/reference/adaptablefieldcontext.md)`) => `[`AdaptableField`](https://www.adaptabletools.com/docs/reference/adaptablefield.md)`[])` | Fields are items in Data Source that are NOT columns but can be used in Expressions (via FIELD keyword) | | | [isColumnQueryable](https://www.adaptabletools.com/docs/reference/expressionoptions.md#iscolumnqueryable) | `(queryableColumnContext: `[`QueryableColumnContext`](https://www.adaptabletools.com/docs/reference/queryablecolumncontext.md)`) => boolean` | Can a given column be included in Expressions | undefined (all columns can be used in Expressions) | | [isExpressionFunctionAvailable](https://www.adaptabletools.com/docs/reference/expressionoptions.md#isexpressionfunctionavailable) | `(context: `[`GlobalExpressionFunctionAvailabilityContext`](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md)`) => boolean` | Whether an Expression Function is available in a given Module (or Column).

Called for each Expression Function and Module combination; return `true`
to make the function available or `false` to hide it. The context includes
`defaultAvailability` (whether the function would be available by default),
which can be returned to keep the standard behaviour.

For **Column Filter** operators the callback is additionally invoked
per-Column with `context.column` (and `context.columnScope`) set, so a
different operator set can be offered per Column. `column` is `undefined`
for the module-level pass, so guard on it before applying per-Column logic.

Hiding a function never disables a symbol operator: hiding `SUM` removes
`SUM(…)` but `+` still works (likewise `=` / `EQ`, `>` / `GT`, `? :` / `IF`).
Keyword operators (`CONTAINS`, `IN`, `CASE`, …) are hidden with their function.

Structural functions (`COL`, `FIELD`, `QUERY`, `DATE`, `$SCOPE`, `NULL`,
`VAR`, `TRUE`, `FALSE`, `AND`, `OR`, `NOT`) cannot be hidden; returning
`false` for them is ignored (and logs a warning). | undefined (all functions have their default availability) | | [liveRefreshIntervalMs](https://www.adaptabletools.com/docs/reference/expressionoptions.md#liverefreshintervalms) | `number` | Repaint cadence (in milliseconds) for cells whose rules depend on the clock
(`NOW()`, `IS_PAST()`, `ROW_AGE{}`) or on a sliding window (`WITHIN(...)`).
`0` disables the live refresh — such cells only repaint on data changes. | 1000 | | [maxHistoryPerCell](https://www.adaptabletools.com/docs/reference/expressionoptions.md#maxhistorypercell) | `number` | Ring-buffer capacity per cell for the observable functions (`CHANGE_COUNT`,
`NET_CHANGE`, `HIGHEST`, `PREVIOUS`, …): how many changes of one cell are
retained for `LAST_N` / cumulative reads. Also the `LAST_N(n)` ceiling. | 1000 | | [maxTimeframeSize](https://www.adaptabletools.com/docs/reference/expressionoptions.md#maxtimeframesize) | `number` | Maximum time (in milliseconds) to hold a Data Change event in a trailing timeframe | 28800000 (~8 hours) | | [performExpressionValidation](https://www.adaptabletools.com/docs/reference/expressionoptions.md#performexpressionvalidation) | `boolean` | Validate Expressions before they can be run or saved | true | | [queryVariables](https://www.adaptabletools.com/docs/reference/expressionoptions.md#queryvariables) | [`QueryVariable`](https://www.adaptabletools.com/docs/reference/queryvariable.md)`[]` | Query variables that can be referenced in Expressions via `VAR('name')`.
Each variable has a name, a static or resolver value, and an optional description.
Evaluated synchronously with each expression evaluation. | | | [supportedAstContractVersions](https://www.adaptabletools.com/docs/reference/expressionoptions.md#supportedastcontractversions) | `number[]` | AST contract versions a ServerSideRowModel / remote evaluator accepts.
Absent means v1 only (raw parse tree). Include `2` to receive
normalized contract-v2 ASTs from `expressionApi.getASTForExpression`. | | `customAggregatedFunctions` entries are an [`AggregatedExpressionFunction`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md): | Property | Type | Description | | --- | --- | --- | | [category](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#category) | `string` | Freeform Functions-menu section for Alert Aggregated / Calculated Column
Aggregated editors. Omit (or use `'Aggregation'`) to list under Aggregation;
any other string becomes its own section label. | | [cumulative](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#cumulative) | `boolean \| \{ currentValue: (context: `[`AggregatedExpressionCumulativeValueContext`](https://www.adaptabletools.com/docs/reference/aggregatedexpressioncumulativevaluecontext.md)`) => any; \}` | Accept a `CUMULATIVE([orderColumn])` clause, e.g.
`MY_AGG{[notional], CUMULATIVE([tradeDate])}`.

- `true` — generic running variant: rows are visited in `CUMULATIVE`
order (per `GROUP_BY` partition when grouped), `reducer` accumulates,
and the value recorded for each row is `processAggregatedValue` (or
the accumulator when absent) evaluated on the prefix so far.
- object — override the per-row read with `currentValue` when
`processAggregatedValue` is too expensive to run per row or the
running value is not a function of the accumulator alone.

Declaring the capability also makes the clause known to validation, the
Expression Editor clause chips / Cumulative editor and the Query Builder. | | [description](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#description) | `string` | What the aggregation evaluates to (outcome), shown in editor
documentation. Often starts with "Returns …". | | [examples](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#examples) | `string[]` | Examples to use the Aggregated Expression Function | | [filterRow](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#filterrow) | `(context: `[`AggregatedExpressionFilterRowContext`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfilterrowcontext.md)`) => boolean` | Optional filter which is applied to each row before the reducer is called. If the filter returns false, the row is NOT included in the aggregation. | | [initialValue](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#initialvalue) | `any` | Mandatory Initial Value for the aggregation.

May be a plain value or a factory function returning a fresh value.
Use a factory when the reducer mutates its accumulator (objects, arrays,
Maps, Sets) — plain object values are deep-cloned per aggregation run
(and per group) for backward compatibility, which is slower. | | [inputTypes](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#inputtypes) | `ExpressionFunctionInputType[]` | Optional argument types. | | [isAvailable](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#isavailable) | [`AdaptableAggregatedExpressionModule`](https://www.adaptabletools.com/docs/reference/adaptableaggregatedexpressionmodule.md)`[] \| ((context: `[`ExpressionFunctionAvailabilityContext`](https://www.adaptabletools.com/docs/reference/expressionfunctionavailabilitycontext.md)`) => boolean)` | Where the function is available — same semantics as standard
`isAvailable`, but restricted to
(Alert Aggregated and Calculated Column Aggregated).
`undefined` means both aggregated expression modules. | | [prepareRowValue](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#preparerowvalue) | `(context: `[`AggregatedExpressionPrepareRowValueContext`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionpreparerowvaluecontext.md)`) => number \| string \| boolean \| Date \| undefined` | Called for each row AFTER the reducer() and processAggregatedValue() functions
Can be used when each row has a different aggregated value (e.g. percentage = row value / aggregated value).
Returns return value for each individual row (a boolean suits a boolean Calculated Column, e.g. "is in the top K") | | [processAggregatedValue](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#processaggregatedvalue) | `(context: `[`AggregatedExpressionProcessAggValueContext`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionprocessaggvaluecontext.md)`) => any` | Called AFTER the reducer() has processed all values / rows
Can be used to change result of reducer based on the values array (e.g. average = aggregated value / count) | | [reducer](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#reducer) | `(context: `[`AggregatedExpressionReducerContext`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionreducercontext.md)`) => any` | Mandatory Reducer function which is called for each value(row) in the Column Data | | [returnType](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#returntype) | [`AggregatedExpressionReturnType`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionreturntype.md) | Static result type of the aggregation. Drives the Calculated Column data
type, the outer expression type check and editor documentation.
`'input'` = same type as the aggregated column (MIN / MAX style). When
omitted the result type is unknown (Calculated Columns default to number). | | [signatures](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#signatures) | `string[]` | Example Signatures for the Aggregated Expression Function | | [weight](https://www.adaptabletools.com/docs/reference/aggregatedexpressionfunction.md#weight) | `boolean` | Accept a `WEIGHT([column])` clause, e.g.
`MY_VWAP{[price], WEIGHT([quantity])}`. The resolved weight of the
current row is delivered as `weightValue` on the `reducer`,
`prepareRowValue` and `filterRow` contexts (and on the cumulative
`currentValue` context). | `editorOptions` is an [`ExpressionEditorOptions`](https://www.adaptabletools.com/docs/reference/expressioneditoroptions.md): | Property | Type | Description | Default | | --- | --- | --- | --- | | [availableEditors](https://www.adaptabletools.com/docs/reference/expressioneditoroptions.md#availableeditors) | [`ExpressionEditors`](https://www.adaptabletools.com/docs/reference/expressioneditors.md) | Which UI editors can be used for Boolean Expressions (Query Builder, Expression Editor, or both).
Takes precedence over `defaultEditor`: if only one editor is listed, that editor is shown
and `defaultEditor` is not evaluated. | ['QueryBuilder', 'ExpressionEditor'] | | [defaultColumnView](https://www.adaptabletools.com/docs/reference/expressioneditoroptions.md#defaultcolumnview) | [`ExpressionEditorColumnView`](https://www.adaptabletools.com/docs/reference/expressioneditorcolumnview.md) | Initial Columns/Fields panel layout in the Expression Editor.
- `collapsed` — column names only (more room for the editor)
- `expanded` — names plus sample/test value inputs | 'collapsed' | | [defaultEditor](https://www.adaptabletools.com/docs/reference/expressioneditoroptions.md#defaulteditor) | [`ExpressionEditorKind`](https://www.adaptabletools.com/docs/reference/expressioneditorkind.md)` \| ((context: `[`DefaultExpressionEditorContext`](https://www.adaptabletools.com/docs/reference/defaultexpressioneditorcontext.md)`) => `[`ExpressionEditorKind`](https://www.adaptabletools.com/docs/reference/expressioneditorkind.md)`)` | Which editor to open first when more than one editor is available.
Receives context (including Module) so the choice can vary by user or surface.
Ignored when `availableEditors` contains a single item.

Overridden to `'ExpressionEditor'` when the current expression cannot be
edited in the Query Builder (non-boolean / value-producing expressions,
advanced constructs such as `QUERY` / `FIELD`, or expressions QB cannot
parse). Empty / new expressions still honour this preference. | 'QueryBuilder' | `expressionEditorButtons` returns [`ExpressionEditorButton`](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md) objects and receives an [`ExpressionEditorButtonsContext`](https://www.adaptabletools.com/docs/reference/expressioneditorbuttonscontext.md): | Property | Type | Description | | --- | --- | --- | | [data](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md#data) | `string` | Text inserted into the editor when the chip is clicked | | [functionName](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md#functionname) | `string` | Registered Expression Function name. When set, the chip is only shown if
that function exists in the editor's function map. Omit for plain-text
inserts (e.g. `"INCREASE"` / `"DECREASE"`). | | [icon](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md#icon) | `string` | Optional icon name (when set, typically shown instead of `text`) | | [newRowAfter](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md#newrowafter) | `boolean` | When true, starts a new toolbar row after this chip | | [text](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md#text) | `string` | Optional label shown on the chip | | Property | Type | Description | | --- | --- | --- | | [defaultButtons](https://www.adaptabletools.com/docs/reference/expressioneditorbuttonscontext.md#defaultbuttons) | [`ExpressionEditorButton`](https://www.adaptabletools.com/docs/reference/expressioneditorbutton.md)`[]` | AdapTable's default buttons for this editor type | | [editorType](https://www.adaptabletools.com/docs/reference/expressioneditorbuttonscontext.md#editortype) | [`ExpressionEditorType`](https://www.adaptabletools.com/docs/reference/expressioneditortype.md) | Coarse editor category: `scalar` \| `aggregated` \| `cumulative` \|
`quantile` \| `window` \| `observable` (the Observable Calculated Column
editor — hosts that add chips to `scalar` usually want them here too) | | [adaptableContext](https://www.adaptabletools.com/docs/reference/expressioneditorbuttonscontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | `fields` entries are an [`AdaptableField`](https://www.adaptabletools.com/docs/reference/adaptablefield.md): | Property | Type | Description | | --- | --- | --- | | [dataType](https://www.adaptabletools.com/docs/reference/adaptablefield.md#datatype) | [`AdaptableColumnDataType`](https://www.adaptabletools.com/docs/reference/adaptablecolumndatatype.md) | Data Type of field, used to validate and show correctly in UI | | [label](https://www.adaptabletools.com/docs/reference/adaptablefield.md#label) | `string` | Label for field (optional - defaults to name) | | [name](https://www.adaptabletools.com/docs/reference/adaptablefield.md#name) | `string` | Name of field in data source, e.g. 'rowId', 'parentObject.childObject.value' | `queryVariables` entries are a [`QueryVariable`](https://www.adaptabletools.com/docs/reference/queryvariable.md): | Property | Type | Description | | --- | --- | --- | | [description](https://www.adaptabletools.com/docs/reference/queryvariable.md#description) | `string` | Optional description shown in the Expression Editor lookups | | [name](https://www.adaptabletools.com/docs/reference/queryvariable.md#name) | `string` | Unique name used to reference the variable in expressions: `VAR('name')` | | [value](https://www.adaptabletools.com/docs/reference/queryvariable.md#value) | [`QueryVariableValue`](https://www.adaptabletools.com/docs/reference/queryvariablevalue.md)` \| ((context: `[`QueryVariableContext`](https://www.adaptabletools.com/docs/reference/queryvariablecontext.md)`) => `[`QueryVariableValue`](https://www.adaptabletools.com/docs/reference/queryvariablevalue.md)`)` | Static value, or resolver evaluated with each expression evaluation | `evaluateAdaptableQLExternally` receives an [`EvaluateExpressionExternallyContext`](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md): | Property | Type | Description | | --- | --- | --- | | [expression](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md#expression) | `string` | Expression to evaluate | | [module](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md#module) | [`AdaptableQLModule`](https://www.adaptabletools.com/docs/reference/adaptableqlmodule.md) | Module being evaluated: Alert, CalculatedColumn, ColumnFilter, GridFilter | | [object](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md#object) | [`AdaptableObject`](https://www.adaptabletools.com/docs/reference/adaptableobject.md) | AdapTable Object which contains the Expression | | [referencedColumns](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md#referencedcolumns) | [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md)`[]` | Columns contained in Expression | | [adaptableContext](https://www.adaptabletools.com/docs/reference/evaluateexpressionexternallycontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | `isColumnQueryable` receives a [`QueryableColumnContext`](https://www.adaptabletools.com/docs/reference/queryablecolumncontext.md): | Property | Type | Description | | --- | --- | --- | | [adaptableContext](https://www.adaptabletools.com/docs/reference/queryablecolumncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | `isExpressionFunctionAvailable` receives a [`GlobalExpressionFunctionAvailabilityContext`](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md): | Property | Type | Description | | --- | --- | --- | | [defaultAvailability](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md#defaultavailability) | `boolean` | Whether the Expression Function would be available by default;
return this value to keep the standard behaviour | | [adaptableContext](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | ---- ## Expression API | Method | Returns | Description | | --- | --- | --- | | [evaluateAggregatedExpression(request)](https://www.adaptabletools.com/docs/reference/expressionapi.md#evaluateaggregatedexpression) | [`ExpressionEvaluationResult`](https://www.adaptabletools.com/docs/reference/expressionevaluationresult.md)`<`[`AggregatedExpressionEvaluationValue`](https://www.adaptabletools.com/docs/reference/aggregatedexpressionevaluationvalue.md)`>` | Evaluates an Aggregation Expression (e.g. `SUM{[price]}`,
`MAX{[price], GROUP_BY([make])}`, `RANK{OVER([price])}`, `SUM{[price]} > 1000`)
and returns a materialized snapshot: the global value, per-group values
(for `GROUP_BY`) and a per-row projection (`getValueForRow`).

When the Expression is a condition, `matches` is whether at least one
aggregation group satisfies it.

Default target is all loaded grid rows. Pass `dataSet` to aggregate a
caller-supplied array, or `rowScope` / `rowFilter` to narrow the grid
set. The snapshot does not update on data changes — re-evaluate when needed.

Under the server-side row model only currently loaded rows are aggregated;
inspect `rowCount` to detect partial data. | | [evaluateStandardExpression(request)](https://www.adaptabletools.com/docs/reference/expressionapi.md#evaluatestandardexpression) | [`ExpressionEvaluationResult`](https://www.adaptabletools.com/docs/reference/expressionevaluationresult.md)`` | Evaluates a Standard Expression against a row.
Requires a row target (`rowNode`, `primaryKeyValue`, or `data`) on the request.
Never throws — returns a result envelope with `success` / `errorMessage`.

The Expression decides the return value: a condition such as `[price] > 100`
yields `true` / `false`; `[price] * 1.19` yields a number.

Direct API evaluation ignores `expressionOptions.evaluateAdaptableQLExternally`
(that option only skips evaluation inside AdapTable features). | | [filterDataSet(request)](https://www.adaptabletools.com/docs/reference/expressionapi.md#filterdataset) | [`ExpressionEvaluationResult`](https://www.adaptabletools.com/docs/reference/expressionevaluationresult.md)`[]>` | Returns the subset of `dataSet` matching a boolean Expression, in original
order and with the same object references. Validation runs once; a
per-row evaluation error fails the whole call. | | [filterRowNodes(request)](https://www.adaptabletools.com/docs/reference/expressionapi.md#filterrownodes) | [`ExpressionEvaluationResult`](https://www.adaptabletools.com/docs/reference/expressionevaluationresult.md)`` | Returns the grid rows matching a boolean Expression, scoped by `rowScope`
and optionally pre-narrowed by `rowFilter`. Validation runs once; a
per-row evaluation error fails the whole call. Matching `IRowNode`s are
returned in source order. | | [getASTForExpression(expression)](https://www.adaptabletools.com/docs/reference/expressionapi.md#getastforexpression) | `any` | AST for remote / SSRM evaluation. Emits a normalized contract-v2 tree
when `expressionOptions.supportedAstContractVersions` includes `2`;
otherwise the raw parse tree (v1). | | [getColumnsFromExpression(expression)](https://www.adaptabletools.com/docs/reference/expressionapi.md#getcolumnsfromexpression) | `string[]` | Returns all Columns referenced in an Expression | | [getExpressionKind(expression, module)](https://www.adaptabletools.com/docs/reference/expressionapi.md#getexpressionkind) | [`ExpressionKind`](https://www.adaptabletools.com/docs/reference/expressionkind.md) | Infers the kind of an Expression from its text: `aggregated` when it contains an
aggregation (e.g. `SUM{[col]}`), `scalar` otherwise — observable reads such as
`CHANGE_COUNT{[col], WITHIN(5m)}` are scalar. Empty or unparseable text yields `scalar`. | | [getExpressionWithColumnFriendlyNames(expression)](https://www.adaptabletools.com/docs/reference/expressionapi.md#getexpressionwithcolumnfriendlynames) | `string \| undefined` | Returns the Expression with Column Headers in place of Column IDs | | [isColumnQueryable(abColumn)](https://www.adaptabletools.com/docs/reference/expressionapi.md#iscolumnqueryable) | `boolean` | Whether a column can be used in an AdapTableQL expression. | | [isValidAggregatedExpression(expression, module, validationErrorMessage)](https://www.adaptabletools.com/docs/reference/expressionapi.md#isvalidaggregatedexpression) | `boolean` | Whether the given AggregatedExpression is valid | | [isValidScalarExpression(expression, module, validationErrorMessage)](https://www.adaptabletools.com/docs/reference/expressionapi.md#isvalidscalarexpression) | `boolean` | Whether the given Expression is valid as a boolean predicate (Alert / Format Column /
Grid Filter / etc.). Root `QUERY("x")` is accepted only when the named query's
declared ReturnType is boolean (or absent). | | [isValidValueExpression(expression, module, validationErrorMessage)](https://www.adaptabletools.com/docs/reference/expressionapi.md#isvalidvalueexpression) | `boolean` | Whether the given Expression is a valid value-producing scalar expression
(any return type — used by Calculated Column and non-boolean Named Queries). | | [migratePreV24Expression(expression, options)](https://www.adaptabletools.com/docs/reference/expressionapi.md#migrateprev24expression) | `\{ expression: string; changed: boolean; error?: string; \}` | Convert a leftover (pre-v24) AdaptableQL string to the v24 greenfield
syntax. Unparseable input is returned unchanged with `error` set.

v24 introduced brace aggregations (`SUM{[price]}`), named operands
(`CUMULATIVE([d])`, `WITHIN(5m)`), and dropped wrappers such as
`CUMUL(...)` and `TIMEFRAME(...)`. Persisted state is rewritten on
load by VersionUpgrade24 when `autoMigrateState` is on. Use this for
a single programmatic / external-config string that has not gone
through that upgrade. The runtime does not accept leftover spellings.

`expressionKind` is the stored module kind. Required for dual-name
paren calls (`SUM([x])` scalar vs aggregation). Omit only when the
leftover is shape-proven (`GROUP_BY` / `CUMUL` / `TIMEFRAME` / …). | | [shouldEvaluateDatesUsingTime(column)](https://www.adaptabletools.com/docs/reference/expressionapi.md#shouldevaluatedatesusingtime) | `boolean` | Whether date comparisons use the full timestamp (exact instant) rather than
the calendar day for the given column — governs the `IN` operator on date
columns and the date Column Filter's distinct-value tree granularity. | | [useCaseSensitivity()](https://www.adaptabletools.com/docs/reference/expressionapi.md#usecasesensitivity) | `boolean` | Whether Expressions are evaluated using Case Sensitivity | See [Evaluating Expressions via the API](https://www.adaptabletools.com/docs/adaptable-ql-expression-evaluation/index.md) for how to call `evaluateStandardExpression` / `evaluateAggregatedExpression` / `filter*`, including external data sets, row narrowing, what-if overrides and the SSRM partial-data caveat.