Calculated Column Technical Reference

Calculated Column State

CalculatedColumnState

Calculated Column section of Adaptable State, including Initial State.

Each entry adds a column whose cells are the result of an AdapTableQL expression. The column is not in the grid data source. ColumnId is the id of the column AdapTable creates. CalculatedColumnSettings.DataType is required. Type can be omitted; it is inferred from the expression.

Extends

BaseState

CalculatedColumns?

CalculatedColumn[]

Calculated Columns to add. ColumnId is the id of the column AdapTable creates.

Calculated Column

CalculatedColumn

A column whose value is an AdapTableQL expression, stored in Adaptable State.

ColumnId is the id of the new column. Expression is required. CalculatedColumnSettings.DataType is required and is the type AdapTable uses for filters and expressions. Type is optional and is inferred from the expression: a per-row expression is Standard, an expression that reads change history is Observable, and an aggregation, cumulative, quantile or window expression is evaluated over rows.

Extends

AdaptableObject

CalculatedColumnSettings

CalculatedColumnSettings

Additional optional properties for Column (e.g. filterable, resizable)

ColumnId

string

Id of the column AdapTable creates. It is not the id of a column already in the data source.

Expression

string

AdapTableQL Expression used to evaluate the Column's value.

The kind is inferred from the text: a per-row expression such as
[quantity] * [price] yields a Standard column; an expression containing
an aggregation such as SUM{[notional], GROUP_BY([sector])} or
[price] / AVG{[price]} is evaluated over the row set.

FriendlyName?

string

Name to be used in Column Header; if blank ColumnId is used

Type?

CalculatedColumnType

Calculated Column category: Standard / Observable (per-row) or
Aggregated / Cumulative / Quantile / Window (over rows).
See .

IsReadOnly?

boolean

Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')

Type is a CalculatedColumnType:

Value
`'Standard'`
`'Observable'`
`'Aggregated'`
`'Cumulative'`
`'Quantile'`
`'Window'`

Calculated Column Settings

CalculatedColumnSettings

Set properties that define Calculated Column's behaviour (all optional except DataType)

SpecialColumnSettings

Column behaviour for a Calculated Column or a Free Text Column.

DataType is required and is the type AdapTable uses for filters and expressions. Filterable, Resizable, Groupable, Sortable, Pivotable and Aggregatable each default to false. SuppressMenu and SuppressMovable default to false, so the header menu is shown and the column can be dragged.

Aggregatable?

boolean

Whether Column can be used in an aggregation when grouping

Default

false

CellDataType?

string

Optional AG Grid cellDataType when it differs from DataType
(e.g. app-registered currency / percentage from dataTypeDefinitions).
When unset, the ColDef uses DataType.

ColumnTypes?

string[]

Custom column types added to AG Grid Column Types when object is created

DataType

AdaptableColumnDataType

Expression's / column value DataType used by AdapTable (AQL, filters, etc.).
Only mandatory property.

Filterable?

boolean

Whether Column is filterable

Default

false

Groupable?

boolean

Whether Column can be grouped

Default

false

HeaderToolTip?

string

Tooltip to show in the Column Header (not cells)

Pivotable?

boolean

Whether Column can be used when grid is in pivot mode

Default

false

Resizable?

boolean

Whether Column can be resized (by dragging column header edges)

Default

false

Sortable?

boolean

Whether Column is sortable

Default

false

SuppressMenu?

boolean

Whether if no menu should be shown for this Column header.

Default

false

SuppressMovable?

boolean

Whether if this Column should be movable via dragging

Default

false

Width?

number

Preferred (pixel) Column Width; if unset, calculated dynamically by AG Grid

ShowToolTip?

boolean

Show underlying Expression as Tooltip when hovering over a cell

Default

false

DataType is an AdaptableColumnDataType:

Value
`'text'`
`'number'`
`'boolean'`
`'date'`
`'object'`
`'textArray'`
`'numberArray'`
`'tupleArray'`
`'objectArray'`
`'groupColumn'`
`'unknown'`

Calculated Column Options

CalculatedColumnOptions

Options for managing Calculated Columns in AdapTable

aggregatedColumnRowChangeThrottle?

number

Coalescing window (in milliseconds) for recomputing Aggregated Calculated
Columns after row data changes (add / update / delete / load).

Bursts of row changes within the window trigger a single recompute of the
aggregated Calculated Columns (the first change recomputes immediately;
subsequent changes within the window are coalesced into one trailing
recompute). Cell-level changes are unaffected — they already refresh only
the Calculated Columns whose referenced columns changed.

Set to 0 to recompute synchronously on every row change (the previous
behaviour).

Default

300

formulaTrace?

FormulaTraceOptions

Options for the Excel-style Formula Trace (highlighting cells that feed a calculated value)

Formula Trace Options

FormulaTraceOptions

Options controlling Formula Trace behaviour for Calculated Columns

enableDoubleClick?

boolean

Show Formula Trace when the user double-clicks a calculated column cell

Default

true

showContextMenuItem?

boolean

Show a "Show Formula" item on the cell context menu for calculated columns

Default

true

Calculated Column Changed Event

The Calculated Column Changed Event fires whenever the Calculated Column State changes.

It provides full information about the new Calculated Column and what triggered the change.

Calculated ColumnChangedInfo

CalculatedColumnChangedInfo

Payload of the CalculatedColumnChanged event.

Fires when a Calculated Column is added, edited or deleted.

Extends , so adaptableApi is included.

Extends

BaseContext

actionName

string

Redux action type: CALCULATED_COLUMN_ADD, CALCULATED_COLUMN_EDIT or CALCULATED_COLUMN_DELETE.

calculatedColumn

CalculatedColumn

Calculated Column that was added, edited or deleted.

calculatedColumnExpressionAST

any

AST for Current Calculated Column Expression.
null when the expression is empty or not currently parsable (e.g. mid-edit).

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

Action Names

The value for the actionName property can be one of:

CALCULATED_COLUMN_ADD
CALCULATED_COLUMN_EDIT
CALCULATED_COLUMN_DELETE

Event Subscription

Subscribing to the Event is done the same way as with all Adaptable Events:

api.eventApi.on(
  'CalculatedColumnChanged',
  (eventInfo: CalculatedColumnChangedInfo) => {
    // do something with the info
  }
);

Calculated Column API

CalculatedColumnApi

Calculated Columns, whose values come from an AdapTableQL expression.

addCalculatedColumn(calcColumn)

returns

CalculatedColumn

Adds new Calculated Column

deleteCalculatedColumn(columnId)

returns

void

Deletes Calculated Column with given ColumnId from Adaptable State

editCalculatedColumn(calcColumn)

returns

CalculatedColumn

Updates given Calculated Column in Adaptable State

getAggregatedCalculatedColumns()

returns

CalculatedColumn[]

Retrieves all Aggregated Calculated Columns in Adaptable State

getCalculatedColumnById(id)

returns

CalculatedColumn

Retrieves Calculated Column by the technical ID (from CalculatedColumnState)

getCalculatedColumnForColumnId(columnId)

returns

CalculatedColumn | undefined

Gets Calculated Column, if any, for given ColumnId

getCalculatedColumns()

returns

CalculatedColumn[]

Retrieves all Calculated Columns in Adaptable State

getCalculatedColumnState()

returns

CalculatedColumnState

Retrieves Calculated Column section from Adaptable State

hideFormulaTrace()

returns

void

Hides the Formula Trace popup (and clears any associated Grid highlights) if it is showing.

openCalculatedColumnSettingsPanel()

returns

void

Opens Settings Panel with Calculated Column section selected and visible

refreshAggregatedCalculatedColumn(columnId)

returns

void

Re-calculates the aggregated CalculatedColumn (whose Expression contains an aggregation) with the given columnId

refreshAggregatedCalculatedColumns()

returns

void

Re-calculates all aggregated CalculatedColumns (whose Expression contains an aggregation, e.g. SUM{[col]})

showFormulaTrace(columnId, primaryKeyValue)

returns

void

Shows the Excel-style Formula Trace popup for a single Calculated Column cell.

This highlights the cells (or column headers) referenced by the Calculated Column's
Expression - using matching colours - and displays a popup showing the annotated formula.

PreviousReferencing Calculated Columns NextAlerts