---
title: "Expressions"
framework: angular
version: "2.1.2"
---

# Expressions

Expressions allow new columns to be generated off of the source data.

```
const expressionFields = [
    {
        id: 'revenue',
        isMeasure: false,
        expression: {
            operator: 'multiply',
            inputs: [
                { id: 'sales.unitPrice' },
                { id: 'sales.quantity' },
            ],
        },
    },
];
```

Expression fields are defined on the [Data Source](https://www.ag-grid.com/studio/angular/data/) as an array of `AgExpressionFieldDefinition`s. Each expression field consists of an field definition (similar to a normal [Field Definition](https://www.ag-grid.com/studio/angular/sync-data#fields)), along with the expression itself.

[See Below](#expression-field-definition) for the expression field API.

## Calculated Columns & Measures

An Expression Field can produce two different outputs:

1. **Calculated Column** - For example `Profit = Revenue - Cost`.
2. **Measure** - For example `Total Profit = SUM(Revenue - Cost)`.

### Calculated Columns

Calculated columns produce multiple outputs for multiple inputs, and can therefore be aggregated in the UI.

You must specify `isMeasure: false` for Calculated Columns.

#### Calculated Columns

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Calculated Columns](https://www.ag-grid.com/studio/examples/expressions/calculated-columns/angular/)

```
const expressionFields = [
    {
        id: 'profit',
        isMeasure: false,
        expression: {
            operator: 'multiply',
            inputs: [
                {
                    operator: 'subtract',
                    inputs: [
                        { id: 'sales.unitPrice' },
                        { id: 'sales.unitCost' },
                    ],
                },
                { id: 'sales.quantity' },
            ],
        },
    },
    // ...
];
```

### Measures

Measures produce a single output from multiple inputs, so the UI cannot aggregate them further.

The [Total Row and Total Columns](https://www.ag-grid.com/studio/angular/building-widgets#totals) still sum each Measure across the table.

You must specify `isMeasure: true` for Measures.

#### Measure Columns

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Measure Columns](https://www.ag-grid.com/studio/examples/expressions/measure-columns/angular/)

```
const expressionFields = [
    {
        id: 'totalProfit',
        isMeasure: true,
        expression: {
            operator: 'subtract',
            inputs: [
                { id: 'sales.unitPrice', aggregation: 'sum' },
                { id: 'sales.unitCost', aggregation: 'sum' },
            ],
        },
    },
    // ...
]
```

## Expression Types

An expression is of one of three types:

1. Function - A function applies an operator to one or more inputs.
2. Value - A value is a fixed value (e.g. number, string, etc.).
3. Field - A field refers to another field (either in the source data, or another expression field).

### Function Expression

```
const functionExpression = {
    operator: 'multiply',
    inputs: [
        { id: 'sales.unitPrice' },
        { value: 100 },
    ],
};
```

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `functionExpression` | `AgFunctionExpression` |  | A function expression applies an operator to one or more inputs. Each input is another expression - a function, value or field. |

[See Below](#function-expression-operators) for the list of function expression operators.

### Value Expression

```
const valueExpression = {
    type: 'number',
    value: 100,
};
```

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `valueExpression` | `AgValueExpression` |  | A value expression is a fixed value (e.g. number, string, etc.). |

### Field Expression

```
const fieldExpression = {
    id: 'sale.profit',
    aggregation: 'sum',
};
```

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `fieldExpression` | `AgFieldExpression` |  | A field expression refers to another field (either in the source data, or another expression field). |

## API

### Expression Field Definition

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `TFormat` |  | The format type of the field (provides default formatting, etc.). If not provided, will be inferred from the expression. |
| `isMeasure` | `boolean` |  | Whether this expression creates a Measure or a Calculated Column. A Calculated Column produces a list of values, e.g. quantity × cost, even without a grouping. A Measure produces a single value e.g. SUM(quantity). |
| `expression` | `AgExpression<TRegistry>` |  | The expression for the field. |
| `id` | `string` |  | Field ID. |
| `name` | `string` |  | Display name. |
| `description` | `string` |  | Field description. Displayed in the Field Panel |
| `hide` | `boolean` |  | Set to `true` to hide from being selected in the UI. Field can still be used for joins. |
| `editable` | `boolean \| AgFieldEditableKey[]` |  | Controls whether the field can be edited in the UI. |
| `serializer` | `AgFieldSerializer<InferDataTypeFromFormat<TRegistry, TFormat>>` |  | Optional. How the field values will be serialized into state. Defaults to format serializer. |
| `deserializer` | `AgFieldDeserializer<InferDataTypeFromFormat<TRegistry, TFormat>>` |  | Optional. How the field values will be deserialized from state. Defaults to format deserializer. |
| `createValueFormatter` | `AgFieldValueFormatterFactory<InferDataTypeFromFormat<TRegistry, TFormat>, TFormatOptions, any>` |  | Optional. Build a value formatter bound to the field's format options and the runtime API. Defaults to format factory. |
| `blankValue` | `string` |  | Optional. How blank values will be displayed. Defaults to format blank value. |
| `formatOptions` | `TFormatOptions` |  | Optional. Will be passed to the value formatter. |

### Function Expression Operators

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `add` | `AgFunctionExpression<TRegistry, "add">` |  | Add two values together. `['number', 'number'] => 'number'` `['string', 'string'] => 'string'` |
| `subtract` | `AgFunctionExpression<TRegistry, "subtract">` |  | Subtract the second value from the first. `['number', 'number'] => 'number'` |
| `multiply` | `AgFunctionExpression<TRegistry, "multiply">` |  | Multiply two values together. `['number', 'number'] => 'number'` |
| `divide` | `AgFunctionExpression<TRegistry, "divide">` |  | Divide the first value by the second. `['number', 'number'] => 'number'` |
| `modulo` | `AgFunctionExpression<TRegistry, "modulo">` |  | Remainder of the first value divided by the second. `['number', 'number'] => 'number'` |
| `equals` | `AgFunctionExpression<TRegistry, "equals">` |  | Are the two values equal? `['number', 'number'] => 'boolean'` `['date', 'date'] => 'boolean'` `['datetime', 'datetime'] => 'boolean'` `['boolean', 'boolean'] => 'boolean'` `['string', 'string'] => 'boolean'` |
| `notEqual` | `AgFunctionExpression<TRegistry, "notEqual">` |  | Are the two values not equal? `['number', 'number'] => 'boolean'` `['date', 'date'] => 'boolean'` `['datetime', 'datetime'] => 'boolean'` `['boolean', 'boolean'] => 'boolean'` `['string', 'string'] => 'boolean'` |
| `lessThan` | `AgFunctionExpression<TRegistry, "lessThan">` |  | Is the first value less than the second? `['number', 'number'] => 'boolean'` |
| `greaterThan` | `AgFunctionExpression<TRegistry, "greaterThan">` |  | Is the first value greater than the second? `['number', 'number'] => 'boolean'` |
| `lessThanOrEqual` | `AgFunctionExpression<TRegistry, "lessThanOrEqual">` |  | Is the first value less than or equal to the second? `['number', 'number'] => 'boolean'` |
| `greaterThanOrEqual` | `AgFunctionExpression<TRegistry, "greaterThanOrEqual">` |  | Is the first value greater than or equal to the second? `['number', 'number'] => 'boolean'` |
| `and` | `AgFunctionExpression<TRegistry, "and">` |  | Are both the values true? `['boolean', 'boolean'] => 'boolean'` |
| `or` | `AgFunctionExpression<TRegistry, "or">` |  | Are either of the values true? `['boolean', 'boolean'] => 'boolean'` |
| `not` | `AgFunctionExpression<TRegistry, "not">` |  | Negates the value. `['boolean'] => 'boolean'` |
| `negate` | `AgFunctionExpression<TRegistry, "negate">` |  | Negates the value. `['number'] => 'number'` |
| `if` | `AgFunctionExpression<TRegistry, "if">` |  | If the first value is true then return the second value, else return the third value. `['boolean', 'string', 'string'] => 'string'` `['boolean', 'number', 'number'] => 'number'` `['boolean', 'boolean', 'boolean'] => 'boolean'` `['boolean', 'date', 'date'] => 'date'` `['boolean', 'datetime', 'datetime'] => 'datetime'` |
| `in` | `AgFunctionExpression<TRegistry, "in">` |  | Is the first value in any of the subsequent values? `['string', ...'string'] => 'boolean'` `['number', ...'number'] => 'boolean'` `['boolean', ...'boolean'] => 'boolean'` `['date', ...'date'] => 'boolean'` `['datetime', ...'datetime'] => 'boolean'` |
| `isTrue` | `AgFunctionExpression<TRegistry, "isTrue">` |  | Is the value true? `['boolean'] => 'boolean'` |
| `isFalse` | `AgFunctionExpression<TRegistry, "isFalse">` |  | Is the value false? `['boolean'] => 'boolean'` |
| `isNull` | `AgFunctionExpression<TRegistry, "isNull">` |  | Is the value null? `['string'] => 'boolean'` `['number'] => 'boolean'` `['boolean'] => 'boolean'` `['date'] => 'boolean'` `['datetime'] => 'boolean'` |
| `isNotNull` | `AgFunctionExpression<TRegistry, "isNotNull">` |  | Is the value not null? `['string'] => 'boolean'` `['number'] => 'boolean'` `['boolean'] => 'boolean'` `['date'] => 'boolean'` `['datetime'] => 'boolean'` |
| `datediff` | `AgFunctionExpression<TRegistry, "datediff">` |  | Return the number of units defined by the first value that are between the second and third values. ['string', 'date', 'date'] => number ['string', 'datetime', 'datetime'] => number Supported units: Milliseconds - `'millisecond' \| 'ms'` Seconds - `'second' \| 'ss' \| 's'` Minutes - `'minute' \| 'mi' \| 'n'` Hours - `'hour' \| 'hh'` Days - `'day' \| 'dy' \| 'y'` Weeks - `'week' \| 'ww' \| 'wk'` Weekdays - `'weekday' \| 'dw' \| 'w'` Months - `'month' \| 'mm' \| 'm'` Quarters -`'quarter' \| 'qq' \| 'q'` Years - `'year' \| 'yyyy' \| 'yy'` Days of year - `'dayofyear'` |
| `dateAdd` | `AgFunctionExpression<TRegistry, "dateAdd">` |  | Add a signed integer interval to a date or datetime. `['date', 'number'] => 'date'` `['datetime', 'number'] => 'datetime'` The unit is supplied via `options.unit`. Supported units: `'year' \| 'quarter' \| 'month' \| 'week' \| 'day'` (and `'hour' \| 'minute'` for datetime only). Month-end clamping applies: adding one month to Jan 31 yields Feb 28/29. |
| `dateFromParts` | `AgFunctionExpression<TRegistry, "dateFromParts">` |  | Construct a date from integer year, 1-based month, and day components. Spine-internal - not valid in calendar range expressions. `['number', 'number', 'number'] => 'date'` |
| `dateTrunc` | `AgFunctionExpression<TRegistry, "dateTrunc">` |  | Truncate a date or datetime to the start of a given unit. `['string', 'date'] => 'date'` `['string', 'datetime'] => 'datetime'` Supported units: `'year' \| 'quarter' \| 'month' \| 'week' \| 'day'` (and `'hour'` for datetime only) |
| `dateEnd` | `AgFunctionExpression<TRegistry, "dateEnd">` |  | Return the end of a date or datetime period for a given unit. `['string', 'date'] => 'date'` `['string', 'datetime'] => 'datetime'` Supported units: `'year' \| 'quarter' \| 'month' \| 'week' \| 'day'` (and `'hour'` for datetime only) |
| `dateExtract` | `AgFunctionExpression<TRegistry, "dateExtract">` |  | Extract a single integer component from a date or datetime. `['string', 'date'] => 'number'` `['string', 'datetime'] => 'number'` Supported units: `'year' \| 'isoYear' \| 'quarter' \| 'month' \| 'week' \| 'day' \| 'hour' \| 'dayOfYear' \| 'dayOfWeek' \| 'monthOfQuarter' \| 'weekOfMonth' \| 'weekend' \| 'timeOfDay' \| 'minute' \| 'second' \| 'dayOfMonth'` |
| `percentiles` | `AgFunctionExpression<TRegistry, "percentiles">` |  | Compute multiple percentiles of the grouped values of the target numeric field. The query compiler fans this out into one output column per `p` value. Planning-level pseudo-function - never evaluated directly. First input: the source numeric field Remaining inputs: percentile values (0-1), one per desired output column |
| `percentile` | `AgFunctionExpression<TRegistry, "percentile">` |  | Compute the value at percentile `p` (0-1) of the grouped values of the target numeric field. This is a planning-level pseudo-function: the query compiler rewrites it into a `groupSorted` + `percentileOf` pair before execution. It is never evaluated directly. `['number', 'number'] => 'number'` |
| `median` | `AgFunctionExpression<TRegistry, "median">` |  | Shorthand for `percentile(field, 0.5)`. Planning-level pseudo-function. `['number'] => 'number'` |
| `currentDate` | `AgFunctionExpression<TRegistry, "currentDate">` |  | Returns the current date as a DATE value. Session-constant: all rows in a single query receive the same value. `[] => 'date'` |
| `currentTimestamp` | `AgFunctionExpression<TRegistry, "currentTimestamp">` |  | Returns the current date and time as a TIMESTAMP value. Session-constant: all rows in a single query receive the same value. `[] => 'datetime'` |
| `abs` | `AgFunctionExpression<TRegistry, "abs">` |  | Returns the absolute value of a number. `['number'] => 'number'` |
| `mod` | `AgFunctionExpression<TRegistry, "mod">` |  | Returns the remainder when the first number is divided by the second (modulo). The sign of the result follows the sign of the dividend. `['number', 'number'] => 'number'` |
| `floor` | `AgFunctionExpression<TRegistry, "floor">` |  | Returns the largest integer less than or equal to the given number. `['number'] => 'number'` |
| `ceiling` | `AgFunctionExpression<TRegistry, "ceiling">` |  | Returns the smallest integer greater than or equal to the given number. `['number'] => 'number'` |
| `round` | `AgFunctionExpression<TRegistry, "round">` |  | Rounds a number to the nearest integer at the specified scale. Uses round-half-away-from-zero semantics. `['number', 'number'] => 'number'` `['number'] => 'number'` (scale defaults to 0) |
| `truncate` | `AgFunctionExpression<TRegistry, "truncate">` |  | Truncates a number to the specified scale toward zero. `['number', 'number'] => 'number'` `['number'] => 'number'` (scale defaults to 0) |
| `power` | `AgFunctionExpression<TRegistry, "power">` |  | Raises the base to the power of the exponent. `['number', 'number'] => 'number'` |
| `exp` | `AgFunctionExpression<TRegistry, "exp">` |  | Returns e raised to the power of the given number. `['number'] => 'number'` |
| `sin` | `AgFunctionExpression<TRegistry, "sin">` |  | Returns the sine of a number in radians. `['number'] => 'number'` |
| `cos` | `AgFunctionExpression<TRegistry, "cos">` |  | Returns the cosine of a number in radians. `['number'] => 'number'` |
| `tan` | `AgFunctionExpression<TRegistry, "tan">` |  | Returns the tangent of a number in radians. `['number'] => 'number'` |
| `asin` | `AgFunctionExpression<TRegistry, "asin">` |  | Returns the arcsine of a number (inverse sine) in radians. Result is in the range [-π/2, π/2]. Input must be in the range [-1, 1]. `['number'] => 'number'` |
| `acos` | `AgFunctionExpression<TRegistry, "acos">` |  | Returns the arccosine of a number (inverse cosine) in radians. Result is in the range [0, π]. Input must be in the range [-1, 1]. `['number'] => 'number'` |
| `atan` | `AgFunctionExpression<TRegistry, "atan">` |  | Returns the arctangent of a number (inverse tangent) in radians. Result is in the range [-π/2, π/2]. `['number'] => 'number'` |
| `atan2` | `AgFunctionExpression<TRegistry, "atan2">` |  | Returns the arctangent of the quotient of two numbers (two-argument arctangent) in radians. Result is in the range [-π, π]. `['number', 'number'] => 'number'` |
| `ln` | `AgFunctionExpression<TRegistry, "ln">` |  | Returns the natural logarithm (base e) of a number. `['number'] => 'number'` |
| `log` | `AgFunctionExpression<TRegistry, "log">` |  | Returns the logarithm of the second number to the base specified by the first number. `['number', 'number'] => 'number'` |
| `log10` | `AgFunctionExpression<TRegistry, "log10">` |  | Returns the base-10 logarithm of a number. `['number'] => 'number'` |
| `greatest` | `AgFunctionExpression<TRegistry, "greatest">` |  | Returns the maximum value of two or more numbers. Returns NULL if any argument is NULL. `['number', ...'number'] => 'number'` |
| `least` | `AgFunctionExpression<TRegistry, "least">` |  | Returns the minimum value of two or more numbers. Returns NULL if any argument is NULL. `['number', ...'number'] => 'number'` |
| `upper` | `AgFunctionExpression<TRegistry, "upper">` |  | Converts a string to uppercase. `['string'] => 'string'` |
| `lower` | `AgFunctionExpression<TRegistry, "lower">` |  | Converts a string to lowercase. `['string'] => 'string'` |
| `substring` | `AgFunctionExpression<TRegistry, "substring">` |  | Extracts a substring from a string. `['string', 'number'] => 'string'` (FROM start position to end of string) `['string', 'number', 'number'] => 'string'` (FROM start position FOR length) Positions are 1-indexed. A start position less than 1 is treated as 1. |
| `position` | `AgFunctionExpression<TRegistry, "position">` |  | Returns the 1-indexed position of the first occurrence of needle in haystack. `['string', 'string'] => 'number'` Returns 0 if needle is not found, 1 if needle is empty. NULL on either argument yields NULL. |
| `ltrim` | `AgFunctionExpression<TRegistry, "ltrim">` |  | Removes the specified characters from the left side of a string. `['string', 'string'] => 'string'` Second argument is a set of characters to strip from the left side. |
| `rtrim` | `AgFunctionExpression<TRegistry, "rtrim">` |  | Removes the specified characters from the right side of a string. `['string', 'string'] => 'string'` Second argument is a set of characters to strip from the right side. |
| `btrim` | `AgFunctionExpression<TRegistry, "btrim">` |  | Removes the specified characters from both sides of a string. `['string', 'string'] => 'string'` Second argument is a set of characters to strip from both ends. |
| `overlay` | `AgFunctionExpression<TRegistry, "overlay">` |  | Replaces a substring with another string at a specified position. `['string', 'string', 'number'] => 'string'` (FROM start, replace to end of replacement) `['string', 'string', 'number', 'number'] => 'string'` (FROM start FOR length) Start position is 1-indexed. When length is omitted, defaults to the replacement length. |
| `like` | `AgFunctionExpression<TRegistry, "like">` |  | SQL `LIKE` wildcard pattern match: `%` matches any sequence of characters, `_` matches any single character. `['string', 'string'] => 'boolean'` `['string', 'string', 'string'] => 'boolean'` (third argument is the `ESCAPE` character) Case-sensitive. NULL text yields NULL. `NOT LIKE` is `not(like(...))`. |
| `sign` | `AgFunctionExpression<TRegistry, "sign">` |  | Returns the sign of a number (-1, 0, or 1). `['number'] => 'number'` Returns -1 for negative, 0 for zero, 1 for positive. NULL input yields NULL. |