# System Filters

Canonical page: https://www.adaptabletools.com/docs/handbook-column-filter-system-filters

- Column Filters use boolean [Expression Functions](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions/index.md) as operators (e.g. `EQ`, `CONTAINS`, `IS_BLANK`, `IS_SAME_DAY`)
- Which operators appear for any given Column depends on its [Data Type](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md)
- Developers can control which Expression Functions are available - globally, per Module, or per Column
- Additionally, Developers can set the default filter operator for each Column or Data Type

Every Column Filter operator is simply a **boolean** [Expression Function](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions/index.md) applied to the filtered Column.

## Filter Operators

When you open a Column Filter, AdapTable ensures that the operator dropdown lists the boolean Expression Functions that apply to that Column's Data Type.

### How Filters Become Expressions

Selecting an operator and value simply builds an [Expression](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md) on the fly.

<b>Examples</b>
- Choosing "Contains" & typing `Ab` produces `[name] CONTAINS "Ab"`
- Choosing "Blanks" produces `IS_BLANK([name])`

## Limiting Available Operators

By default every boolean Expression Function applicable to a Column's Data Type is offered.

To restrict this, use the `isExpressionFunctionAvailable` property in [Expression Options](https://www.adaptabletools.com/docs/technical-reference-expression/index.md).

### `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.module` (and, for filters, `context.column`):

```ts {4,5,6,7,8,9}
// Hide the REGEX operator from Column Filters everywhere
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    isExpressionFunctionAvailable: (
      context: GlobalExpressionFunctionAvailabilityContext
    ) => {
      if (
        context.module === 'ColumnFilter' &&
        context.functionName === 'REGEX'
      ) {
        return false;
      }
      return context.defaultAvailability;
    },
  },
};
```

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

This lets you offer a different operator set for each Column.

- `context.column` is `undefined` during the Module-level pass
- Accordingly you should always guard on it before applying per-Column logic

```ts {6,7,8,9,10,11,12}
// Offer a different operator set per Column
const adaptableOptions: AdaptableOptions = {
  expressionOptions: {
    isExpressionFunctionAvailable: (
      context: GlobalExpressionFunctionAvailabilityContext
    ) => {
      if (context.module !== 'ColumnFilter' || !context.column) {
        return context.defaultAvailability;
      }
      return context.column.columnId === 'name'
        ? ['CONTAINS', 'ENDS_WITH', 'REGEX'].includes(context.functionName)
        : ['CONTAINS', 'GT', 'EQ', 'IS_THIS_MONTH', 'IN'].includes(
            context.functionName
          );
    },
  },
};
```

**Example: System Filters**

Limiting which filter operators are available per Column

- This demo uses `isExpressionFunctionAvailable` to limit the operators offered in each Column's Filter dropdown:
  - The `Name` Column offers only the `CONTAINS`, `ENDS_WITH` and `REGEX` operators
  - All other Columns offer whichever of `CONTAINS`, `GT`, `EQ`, `IS_THIS_MONTH` and `IN` are relevant to that Column's Data Type

- Open the various filter dropdowns and see that there is a much reduced list of operators available
- Open the `Name` dropdown and see that the list provided just for that Column is shown

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: 'System Filters',
  expressionOptions: {
    isExpressionFunctionAvailable: (
      context: GlobalExpressionFunctionAvailabilityContext
    ) => {
      // Only limit the operators offered in the Column Filter dropdown, and
      // only in the per-Column pass (when `context.column` is set). Everything
      // else keeps its default availability.
      if (context.module !== 'ColumnFilter' || !context.column) {
        return context.defaultAvailability;
      }
      const allowed =
        context.column.columnId === 'name'
          ? ['CONTAINS', 'ENDS_WITH', 'REGEX']
          : ['CONTAINS', 'GT', 'EQ', 'IS_THIS_MONTH', 'IN'];
      return allowed.includes(context.functionName);
    },
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['ColumnFilter'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout', 'ColumnFilter'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'topics',
            'license',
            'created_at',
            'has_wiki',
            'updated_at',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
          ColumnFilters: [
            {
              ColumnId: 'language',
              Expression: '[language] IN ("TypeScript", "HTML")',
            },
            {
              ColumnId: 'github_stars',
              Expression: '[github_stars] > 15000',
            },
          ],
        },
      ],
    },
  },
};
```

## Default Filters

AdapTable sets a default filter operator to use for 4 Column Data Types.

However, each of these can be changed by using a relevant property in [Column Filter Options](https://www.adaptabletools.com/docs/technical-reference-filter/index.md):

| Data Type | Options Property                              | Default                        | Available Values                                                            |
| --------- | --------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- |
| text      | `defaultTextColumnFilter`    | `CONTAINS`    | `EQ` `NEQ` `CONTAINS` `NOT_CONTAINS` `STARTS_WITH` `ENDS_WITH` `REGEX` `IN` `NOT_IN` `IS_BLANK` `IS_NOT_BLANK` |
| numeric   | `defaultNumericColumnFilter` | `EQ`          | `GT` `GTE` `LT` `LTE` `EQ` `NEQ` `IN` `NOT_IN` `IS_BLANK` `IS_NOT_BLANK`                                       |
| date      | `defaultDateColumnFilter`    | `IS_SAME_DAY` | `EQ` `NEQ` `GT` `GTE` `LT` `LTE` `IS_SAME_DAY` `IS_DIFFERENT_DAY` `IN` `NOT_IN` `IS_BLANK` `IS_NOT_BLANK`      |
| array     | `defaultArrayColumnFilter`   | `IN`          | `IN` `NOT_IN` `IS_BLANK` `IS_NOT_BLANK`                                                                        |

It is also possible to set a **different** default filter operator to display in the Filter Bar and the Filter Form

Each property offers two types of return value:

- a filter operator (relevant to the data type) directly
- a function which receives an [`DefaultFilterExpressionContext`](https://www.adaptabletools.com/docs/reference/defaultfilterexpressioncontext.md) object, and returns the filter operator

This is particularly useful in the [Filter Bar](https://www.adaptabletools.com/docs/handbook-column-filter-components/index.md) as it sets the filter operator that is displayed by default for the Column

**Example: Default Filters**

Setting new default operators for Filters

- This example sets the 4 different data-type related default filter operator properties:
  - `defaultNumericColumnFilter` - **GT** for *Filter Bar* and **LT** for *Filter Form* (provided hard-coded for both, so is same for all numeric columns)
  - `defaultTextColumnFilter` - **STARTS_WITH** for all string columns except `Language` which is **IN**
  - `defaultDateColumnFilter` - **LT** for `Created` and `Updated` columns, and **GT** for all other date columns
  - `defaultArrayColumnFilter` - **NOT_IN** (provided hard-coded so is same for all array columns)

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,
  DefaultFilterExpressionContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Filter Default Expression Function',
  filterOptions: {
    columnFilterOptions: {
      defaultNumericColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.filterComponent === 'FilterBar'
          ? 'GT'
          : 'LT';
      },
      defaultTextColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'language' ? 'IN' : 'STARTS_WITH';
      },
      defaultDateColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'created_at' ||
          context.column.columnId == 'updated_at'
          ? 'LT'
          : 'GT';
      },
      defaultArrayColumnFilter: 'NOT_IN',
    },
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['ColumnFilter'],
      PinnedToolbars: ['ColumnFilter'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout', 'ColumnFilter'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'created_at',
            'pushed_at',
            'topics',
            'updated_at',
            'github_watchers',
            'license',
            'has_projects',
            'has_pages',
            'has_wiki',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          ColumnSizing: {
            name: {Width: 100},
            language: {Width: 140},
            github_stars: {Width: 130},
            created_at: {Width: 160},
            pushed_at: {Width: 160},
            topics: {Width: 300},
            updated_at: {Width: 160},
            github_watchers: {Width: 130},
            license: {Width: 100},
            has_projects: {Width: 100},
            has_pages: {Width: 100},
            has_wiki: {Width: 100},
            week_issue_change: {Width: 100},
          },
        },
      ],
    },
  },
};
```

### Default Text Filter

Use the `defaultTextColumnFilter` property to set the default filter operator for text columns.

### `defaultTextColumnFilter`

Default filter operator to use for Text (string) Columns

Sets the default filter operator to use for string / text Columns.

Options are: `EQ`, `NEQ`, `CONTAINS` (the default value), `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`, `REGEX`, `IS_BLANK`, `IS_NOT_BLANK`

This can be provided as a 'hard-coded' value:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultTextColumnFilter: 'STARTS_WITH',
    },
  },
};
```

Or via a function which receives [`DefaultFilterExpressionContext`](https://www.adaptabletools.com/docs/reference/defaultfilterexpressioncontext.md) and returns a Text filter operator:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultTextColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'language' ? 'IN' : 'STARTS_WITH';
      },
    },
  },
};
```

### Default Numeric Filter

Use the `defaultNumericColumnFilter` property to set the default filter operator for Numeric columns.

### `defaultNumericColumnFilter`

Default filter operator to use for Numeric Columns

Sets the default filter operator to use for numeric Columns.

Options for this property are: `GT`, `GTE`, `LT`, `LTE`, `EQ` (the default value), `NEQ`, `IN`, `NOT_IN`, `IS_BLANK`, `IS_NOT_BLANK`

This can be provided as a 'hard-coded' value:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultNumericColumnFilter: 'GT',
    },
  },
};
```

Or via a function which receives [`DefaultFilterExpressionContext`](https://www.adaptabletools.com/docs/reference/defaultfilterexpressioncontext.md) and returns a Numeric filter operator:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultNumericColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'github_stars' ? 'GT' : 'LT';
      },
    },
  },
};
```

### Default Date Filter

Use the `defaultDateColumnFilter` property to set the default filter for Date columns.

`'IS_SAME_DAY'` matches the same calendar day. Use `'EQ'` when you need exact timestamp equality.

### `defaultDateColumnFilter`

Default filter operator to use for Date Columns

Sets the default filter operator to use for date Columns.

Options are: `IS_SAME_DAY` (the default value), `IS_DIFFERENT_DAY`, `GT` (after), `GTE`, `LT` (before), `LTE`, `EQ`, `NEQ`, `IN`, `NOT_IN`, `IS_BLANK`, `IS_NOT_BLANK`

This can be provided as a 'hard-coded' value:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultDateColumnFilter: 'GT',
    },
  },
};
```

Or via a function which receives [`DefaultFilterExpressionContext`](https://www.adaptabletools.com/docs/reference/defaultfilterexpressioncontext.md) and returns a Date filter operator:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultDateColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'created_at' ? 'LT' : 'GT';
      },
    },
  },
};
```

### Default Array Filter

Use the `defaultArrayColumnFilter` property to set the default filter operator for Array (text and numeric) columns.

### `defaultArrayColumnFilter`

Default filter operator to use for Array-based Columns

Sets the default filter operator to use for Array Columns (both string and numeric).

Options are: `IN` (the default value), `NOT_IN`, `IS_BLANK`, `IS_NOT_BLANK`

This can be provided as a 'hard-coded' value:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultArrayColumnFilter: 'IS_BLANK',
    },
  },
};
```

Or via a function which receives [`DefaultFilterExpressionContext`](https://www.adaptabletools.com/docs/reference/defaultfilterexpressioncontext.md) and returns an Array filter operator:

```ts {4}
const adaptableOptions: AdaptableOptions = {
  filterOptions: {
    columnFilterOptions: {
      defaultArrayColumnFilter: (context: DefaultFilterExpressionContext) => {
        return context.column.columnId == 'History' ? 'IS_BLANK' : 'IN';
      },
    },
  },
};
```

## Appendix: System Filter List

The boolean functions used as filter operators, by Data Type, are broadly:

<b>Text Columns</b>

- `EQ`, `NEQ`
- `CONTAINS`, `NOT_CONTAINS`
- `STARTS_WITH`, `ENDS_WITH`
- `REGEX`
- `IN`, `NOT_IN`
- `IS_BLANK`, `IS_NOT_BLANK`

<b>Numeric Columns</b>

- `EQ`, `NEQ`
- `GT`, `GTE`, `LT`, `LTE`
- `IN`, `NOT_IN`
- `IS_POSITIVE`, `IS_NEGATIVE`
- `IS_BLANK`, `IS_NOT_BLANK`

<b>Date Columns</b>

- `EQ`, `NEQ` (exact timestamp)
- `GT` (after), `GTE` (on or after), `LT` (before), `LTE` (on or before)
- `IS_SAME_DAY`, `IS_DIFFERENT_DAY`
- `IN`, `NOT_IN`
- `IS_TODAY`, `IS_YESTERDAY`, `IS_TOMORROW`
- `IS_THIS_WEEK`, `IS_THIS_MONTH`, `IS_THIS_QUARTER`, `IS_THIS_YEAR`
- `IS_PAST`, `IS_FUTURE`, `IS_BEFORE_TODAY`, `IS_AFTER_TODAY`
- `IS_WORKDAY`, `IS_NEXT_WORKDAY`, `IS_PREV_WORKDAY`, `IS_HOLIDAY`
- `IS_BLANK`, `IS_NOT_BLANK`

<b>Boolean Columns</b>

- `EQ` (with a checkbox editor), `NEQ`
- `IS_BLANK`, `IS_NOT_BLANK`

<b>Array Columns</b>

- `IN`, `NOT_IN`
- `IS_BLANK`, `IS_NOT_BLANK`

Array Columns are [AG Grid array types](https://www.adaptabletools.com/docs/dev-guide-aggrid-array-columns/index.md) (`textArray` / `numberArray`). `IN` / `NOT_IN` match when any element of the cell array is in the selection.
