# Calculated Column Technical Reference

Canonical page: https://www.adaptabletools.com/docs/technical-reference-calculated-column

## Calculated Column State

| Property | Type | Description |
| --- | --- | --- |
| [CalculatedColumns](https://www.adaptabletools.com/docs/reference/calculatedcolumnstate.md#calculatedcolumns) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md)`[]` | Calculated Columns to add. `ColumnId` is the id of the column AdapTable creates. |

### Calculated Column

| Property | Type | Description |
| --- | --- | --- |
| [CalculatedColumnSettings](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#calculatedcolumnsettings) | [`CalculatedColumnSettings`](https://www.adaptabletools.com/docs/reference/calculatedcolumnsettings.md) | Additional optional properties for Column (e.g. filterable, resizable) |
| [ColumnId](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#columnid) | `string` | Id of the column AdapTable creates. It is not the id of a column already in the data source. |
| [Expression](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#expression) | `string` | AdapTableQL Expression used to evaluate the Column&#39;s value.<br/><br/>The kind is inferred from the text: a per-row expression such as<br/>`[quantity] * [price]` yields a Standard column; an expression containing<br/>an aggregation such as `SUM{[notional], GROUP_BY([sector])}` or<br/>`[price] / AVG{[price]}` is evaluated over the row set. |
| [FriendlyName](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#friendlyname) | `string` | Name to be used in Column Header; if blank `ColumnId` is used |
| [Type](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#type) | [`CalculatedColumnType`](https://www.adaptabletools.com/docs/reference/calculatedcolumntype.md) | Calculated Column category: `Standard` / `Observable` (per-row) or<br/>`Aggregated` / `Cumulative` / `Quantile` / `Window` (over rows).<br/>See . |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

`Type` is a [`CalculatedColumnType`](https://www.adaptabletools.com/docs/reference/calculatedcolumntype.md):

[See API: calculatedcolumntype](https://www.adaptabletools.com/docs/reference/calculatedcolumntype.md)

### Calculated Column Settings

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [ShowToolTip](https://www.adaptabletools.com/docs/reference/calculatedcolumnsettings.md#showtooltip) | `boolean` | Show underlying Expression as Tooltip when hovering over a cell | false |

`DataType` is an [`AdaptableColumnDataType`](https://www.adaptabletools.com/docs/reference/adaptablecolumndatatype.md):

[See API: adaptablecolumndatatype](https://www.adaptabletools.com/docs/reference/adaptablecolumndatatype.md)

---

## Calculated Column Options

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [aggregatedColumnRowChangeThrottle](https://www.adaptabletools.com/docs/reference/calculatedcolumnoptions.md#aggregatedcolumnrowchangethrottle) | `number` | Coalescing window (in milliseconds) for recomputing Aggregated Calculated<br/>Columns after row data changes (add / update / delete / load).<br/><br/>Bursts of row changes within the window trigger a single recompute of the<br/>aggregated Calculated Columns (the first change recomputes immediately;<br/>subsequent changes within the window are coalesced into one trailing<br/>recompute). Cell-level changes are unaffected — they already refresh only<br/>the Calculated Columns whose referenced columns changed.<br/><br/>Set to `0` to recompute synchronously on every row change (the previous<br/>behaviour). | 300 |
| [formulaTrace](https://www.adaptabletools.com/docs/reference/calculatedcolumnoptions.md#formulatrace) | [`FormulaTraceOptions`](https://www.adaptabletools.com/docs/reference/formulatraceoptions.md) | Options for the Excel-style Formula Trace (highlighting cells that feed a calculated value) |   |

### Formula Trace Options

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [enableDoubleClick](https://www.adaptabletools.com/docs/reference/formulatraceoptions.md#enabledoubleclick) | `boolean` | Show Formula Trace when the user double-clicks a calculated column cell | true |
| [showContextMenuItem](https://www.adaptabletools.com/docs/reference/formulatraceoptions.md#showcontextmenuitem) | `boolean` | Show a &quot;Show Formula&quot; item on the cell context menu for calculated columns | 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

| Property | Type | Description |
| --- | --- | --- |
| [actionName](https://www.adaptabletools.com/docs/reference/calculatedcolumnchangedinfo.md#actionname) | `string` | Redux action type: `CALCULATED_COLUMN_ADD`, `CALCULATED_COLUMN_EDIT` or `CALCULATED_COLUMN_DELETE`. |
| [calculatedColumn](https://www.adaptabletools.com/docs/reference/calculatedcolumnchangedinfo.md#calculatedcolumn) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md) | Calculated Column that was added, edited or deleted. |
| [calculatedColumnExpressionAST](https://www.adaptabletools.com/docs/reference/calculatedcolumnchangedinfo.md#calculatedcolumnexpressionast) | `any` | AST for Current Calculated Column Expression.<br/>`null` when the expression is empty or not currently parsable (e.g. mid-edit). |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/calculatedcolumnchangedinfo.md#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](https://www.adaptabletools.com/docs/technical-reference-adaptable-events/index.md):

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

---

## Calculated Column API

| Method | Returns | Description |
| --- | --- | --- |
| [addCalculatedColumn(calcColumn)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#addcalculatedcolumn) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md) | Adds new Calculated Column |
| [deleteCalculatedColumn(columnId)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#deletecalculatedcolumn) | `void` | Deletes Calculated Column with given ColumnId from Adaptable State |
| [editCalculatedColumn(calcColumn)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#editcalculatedcolumn) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md) | Updates given Calculated Column in Adaptable State |
| [getAggregatedCalculatedColumns()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#getaggregatedcalculatedcolumns) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md)`[]` | Retrieves all Aggregated Calculated Columns in Adaptable State |
| [getCalculatedColumnById(id)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#getcalculatedcolumnbyid) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md) | Retrieves Calculated Column by the technical ID (from `CalculatedColumnState`) |
| [getCalculatedColumnForColumnId(columnId)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#getcalculatedcolumnforcolumnid) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md)` \| undefined` | Gets Calculated Column, if any, for given ColumnId |
| [getCalculatedColumns()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#getcalculatedcolumns) | [`CalculatedColumn`](https://www.adaptabletools.com/docs/reference/calculatedcolumn.md)`[]` | Retrieves all Calculated Columns in Adaptable State |
| [getCalculatedColumnState()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#getcalculatedcolumnstate) | [`CalculatedColumnState`](https://www.adaptabletools.com/docs/reference/calculatedcolumnstate.md) | Retrieves Calculated Column section from Adaptable State |
| [hideFormulaTrace()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#hideformulatrace) | `void` | Hides the Formula Trace popup (and clears any associated Grid highlights) if it is showing. |
| [openCalculatedColumnSettingsPanel()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#opencalculatedcolumnsettingspanel) | `void` | Opens Settings Panel with Calculated Column section selected and visible |
| [refreshAggregatedCalculatedColumn(columnId)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#refreshaggregatedcalculatedcolumn) | `void` | Re-calculates the aggregated CalculatedColumn (whose Expression contains an aggregation) with the given `columnId` |
| [refreshAggregatedCalculatedColumns()](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#refreshaggregatedcalculatedcolumns) | `void` | Re-calculates all aggregated CalculatedColumns (whose Expression contains an aggregation, e.g. `SUM{[col]}`) |
| [showFormulaTrace(columnId, primaryKeyValue)](https://www.adaptabletools.com/docs/reference/calculatedcolumnapi.md#showformulatrace) | `void` | Shows the Excel-style Formula Trace popup for a single Calculated Column cell.<br/><br/>This highlights the cells (or column headers) referenced by the Calculated Column&#39;s<br/>Expression - using matching colours - and displays a popup showing the annotated formula. |