# Managing Expressions

Canonical page: https://www.adaptabletools.com/docs/adaptable-ql-expression-managing

- AdapTable allows developers to reduce the AdapTableQL functionality on offer to users
- This is often the case if you are evaluating Expressions yourself externally instead of using AdapTableQL
- In particular 2 features are provided:
  - Make some Expression Functions unavailable in the [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md) and for AdapTableQL evaluation
  - Specify that certain Columns cannot be included in Expressions

## Reducing Expression Complexity

AdapTable provides a couple of helpful features to reduce the complexity of the Expressions available to users.

This is particularly useful if [you are evaluating Expressions on the Server](https://www.adaptabletools.com/docs/adaptable-server-evaluation/index.md) using your own translation

### Limiting Available AdapTableQL Functions
  
By default **all** [Expression Functions](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions/index.md) are available in the [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md) and available for the AdapTableQL evaluation engine.

Use `isExpressionFunctionAvailable` in [Expression Options](https://www.adaptabletools.com/docs/technical-reference-expression/index.md) to hide functions globally, per Module, or (for Column Filter) per Column.

### `isExpressionFunctionAvailable`

Control which Expression Functions are available (globally, per Module, or per Column)

This is a function called for each Expression Function / Module combination; return `true` to make the function available or `false` to hide it.

It receives a [`GlobalExpressionFunctionAvailabilityContext`](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [defaultAvailability](https://www.adaptabletools.com/docs/reference/globalexpressionfunctionavailabilitycontext.md#defaultavailability) | `boolean` | Whether the Expression Function would be available by default;<br/>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` |

Return `context.defaultAvailability` to keep standard behaviour for any function you don't want to change

Because it runs for **every** Module and function, scope your logic before restricting anything - typically by checking `context.functionName` and `context.module`:

```ts
// Hide SUM everywhere; hide LOWER and UPPER only in Calculated Column
expressionOptions: {
  isExpressionFunctionAvailable: (
    context: GlobalExpressionFunctionAvailabilityContext
  ) => {
    if (context.functionName === 'SUM') {
      return false;
    }
    if (
      context.module === 'CalculatedColumn' &&
      (context.functionName === 'LOWER' || context.functionName === 'UPPER')
    ) {
      return false;
    }
    return context.defaultAvailability;
  },
};
```

For **Column Filter** operators the function is additionally called **per Column**, with `context.column` (and `context.columnScope`) set.

This allows a different set of filter operators to be offered for each Column:

```ts
// Offer only 3 text operators in the Name Column's Filter
expressionOptions: {
  isExpressionFunctionAvailable: (
    context: GlobalExpressionFunctionAvailabilityContext
  ) => {
    if (context.module !== 'ColumnFilter' || !context.column) {
      return context.defaultAvailability;
    }
    if (context.column.columnId === 'name') {
      return ['CONTAINS', 'ENDS_WITH', 'REGEX'].includes(context.functionName);
    }
    return context.defaultAvailability;
  },
};
```

See [Limiting Available Operators](https://www.adaptabletools.com/docs/handbook-column-filter-system-filters/index.md#limiting-available-operators) for a demo which limits the operators for every Column

- Custom functions can also set `isAvailable` on the function itself — see [Custom Expression Functions Scope](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions-custom-scope/index.md)
- `isExpressionFunctionAvailable` runs after that per-function result (`context.defaultAvailability`)

#### Operators

Hiding a function never disables a symbol operator - so hiding `SUM` removes `SUM([Price], [Tax])`, but `[Price] + [Tax]` still works.

The same applies to every symbol operator, e.g.:

| Hidden Function | Still Works           |
| --------------- | --------------------- |
| `SUM`           | `[Price] + [Tax]`     |
| `EQ`            | `[Currency] = 'USD'`  |
| `GT`            | `[PnL] > 0`           |
| `IF`            | `[PnL] > 0 ? 'Profit' : 'Loss'` |

Keyword operators - e.g. `CONTAINS`, `STARTS_WITH`, `IN` and `CASE` - are spelt exactly like their function, so they **are** hidden with it

#### Structural Functions

A few functions are part of the structure of AdapTableQL and are always available: `COL`, `FIELD`, `QUERY`, `DATE`, `$SCOPE`, `NULL`, `VAR`, `TRUE`, `FALSE`, `AND`, `OR` and `NOT`.

Returning `false` for any of these is ignored (and AdapTable logs a warning in the console)

**Example: AdapTableQL: Limiting Functions**

Removes some System AdapTableQL Expression Functions

### Expand to see the Expressions removed

```ts
expressionOptions: {
  isExpressionFunctionAvailable: (
    context: GlobalExpressionFunctionAvailabilityContext
  ) => {
    if (context.functionName === 'SUM') {
      return false;
    }
    if (
      context.module === 'CalculatedColumn' &&
      (context.functionName === 'LOWER' || context.functionName === 'UPPER')
    ) {
      return false;
    }
    return context.defaultAvailability;
  },
},
```

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableOptions,
  GlobalExpressionFunctionAvailabilityContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Limiting Expression Functions',
  expressionOptions: {
    isExpressionFunctionAvailable: (
      context: GlobalExpressionFunctionAvailabilityContext
    ) => {
      if (context.functionName === 'SUM') {
        return false;
      }
      if (
        context.module === 'CalculatedColumn' &&
        (context.functionName === 'LOWER' || context.functionName === 'UPPER')
      ) {
        return false;
      }
      return context.defaultAvailability;
    },
  },

  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
      ModuleButtons: ['CalculatedColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

### Limiting Queryable Columns

By default all Columns in AdapTable can be used in a Query.

To specify whether or not a given column is Queryable, provide an implementation for the `isColumnQueryable` property of [Expression Options](https://www.adaptabletools.com/docs/technical-reference-expression/index.md).

### `isColumnQueryable`

Whether a Column should be included in AdapTableQL Expressions

Custom function which specifies if a Column should be included in AdapTableQL Expressions.

This is often used in conjunction with the [Server-Side Row Model](https://www.adaptabletools.com/docs/dev-guide-row-models-server-overview/index.md) to reduce the complexity of an Expression

The function receives a [`QueryableColumnContext`](https://www.adaptabletools.com/docs/reference/queryablecolumncontext.md) object (which simply contains the Column) and returns a boolean:

If you want **all** columns in the Grid to be available, do not provide an implementation for this function

```ts
// Don't allow Date columns to be queryable
  expressionOptions:{
    isColumnQueryable: (queryableColumnContext: QueryableColumnContext) => { 
      return queryableColumnContext.column.dataType != 'date' 
    },
};
```

If no implementation is provided, all Columns can be used in Expressions

Use `filter` and `floatingFilter` properties in GridOptions to set which Columns can be **filtered**

**Example: AdapTableQL: Limiting Columns**

Set some columns to be non queryable

- In this example we have provided an implementation for the `isColumnQueryable` property to prevent these columns from being used in Expressions:
  - The `License` Column
  - All `Date` Columns
### Expand to see how Queryable Columns were set

```ts
expressionOptions: {
  isColumnQueryable: (queryableColumnContext: QueryableColumnContext) => {
    return (
      queryableColumnContext.column.dataType != 'date' &&
      queryableColumnContext.column.columnId != 'license'
    );
  },
},
```

- Open the Grid Filter (by clicking the arrows icon in the Grid Filter toolbar)
- In both the Expression Editor and the Query Builder, note that License and all Date Columns are absent from the Column list 

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableOptions,
  QueryableColumnContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Limiting Queryable Columns',
  expressionOptions: {
    isColumnQueryable: (queryableColumnContext: QueryableColumnContext) => {
      return (
        queryableColumnContext.column.dataType != 'date' &&
        queryableColumnContext.column.columnId != 'license'
      );
    },
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Case Sensitivity

By default Expressions are **case insensitive**. 

Set `caseSensitiveExpressions` in `ExpressionOptions` to _true_ to change that.

### `caseSensitiveExpressions`

Keep case sensitivity when AdapTableQL evaluates string-based Expressions

By default AdapTableQL will ignore case in its evaluations.

Set this property to _true_ to enforce case sensitivity.

```ts {4}
// Enforce case sensitivity in AdapTable QL for string evaluations
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    caseSensitiveExpressions: true,
  },
};
```

## Date Comparisons

By default date Expressions compare **calendar days**, not the full timestamp.

Set `evaluateDatesUsingTime` in `ExpressionOptions` to _true_ to compare the exact instant.

### `evaluateDatesUsingTime`

Compare dates as a full timestamp rather than a calendar day

By default AdapTableQL compares dates by calendar day.

Set this property to _true_ to compare the full timestamp (or provide a function to decide per Column).

This applies wherever Expressions evaluate `IN` on a Date Column — Queries, Styled Columns, Alerts, Column Filters, and so on.

It also controls whether the date Column Filter's [In Filter](https://www.adaptabletools.com/docs/handbook-column-filter-in-filter/index.md#filtering-on-time) tree drills down to individual times.

When an `IN` right-hand value is an ISO string containing `T`, the exact instant is used regardless of this setting

```ts {4}
// Compare every Date Column as a full timestamp
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    evaluateDatesUsingTime: true,
  },
};
```

```ts {4-6}
// Compare time only for the Created column
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    evaluateDatesUsingTime: (context: AdaptableColumnContext) => {
      return context.column.columnId === 'created_at';
    },
  },
};
```
