# AdapTable Grid Filter

Canonical page: https://www.adaptabletools.com/docs/handbook-grid-filter

- The Grid Filter searches the grid’s data and shows only matching rows
- It is a property of a [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md) and  complements (and can be used together with) [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md)
- Grid Filters wrap (Boolean) [Expressions](https://www.adaptabletools.com/docs/adaptable-ql-expression-standard/index.md) which are evaluated by [AdapTableQL](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md)
- Boolean Expressions can contain multiple conditions and operators and reference numerous columns
- Grid Filters can be named and saved as Named Queries and then re-run as often as required

The AdapTable Grid Filter allows users to run complex, multi-condition searches across multiple Columns.

These will then be evaluated across the whole of AG Grid's data source.

- Grid Filters complement, and are designed to work in conjunction, with [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md)
- Both Grid and Column Filters can be active at the same time

AdapTable will display **only** those rows that match **all** the Conditions in the Grid Filter.

Grid Filters differ from [Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search/index.md) in that they display matching rows, rather than highlight matching cells

The Grid Filter is saved (and can be defined) in the Current [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md).

- There can only be **one** active Grid Filter at any time
- Unlike [Calculated Columns](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md) which can return <b>any</b> value, Grid Filter Expressions <b>must always return a Boolean</b>

## Expressions

Grid Filters are essentially wrappers around [Boolean Expressions](https://www.adaptabletools.com/docs/adaptable-ql-expression-standard/index.md) - powerful, configurable, querying constructs that can contain multiple conditions and operators and will return a **boolean** (true/false) result.

As with all Expressions, Grid Filters are evaluated by [AdapTableQL](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md) - AdapTable's native Query Language.

AdapTable provides two UI components to facilitate the creation of the Grid Filter Expression:
- a [Query Builder](https://www.adaptabletools.com/docs/ui-query-builder/index.md) for straightforward Expressions
- an [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md) for more complex requirements

The Grid Filter Toolbar works especially well when [Pinned](https://www.adaptabletools.com/docs/ui-dashboard-tabs-toolbars/index.md#pinned-toolbars) above the Grid

Both open in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md) (via the Expand button, or by clicking the expression summary in the Toolbar).

Once created, the Expression is shown as a **summary** in the [Grid Filter Toolbar](https://www.adaptabletools.com/docs/ui-dashboard/index.md#tabs-and-toolbars) (it is not edited in place)

**Example: Applying a Grid Filter**

Using AdapTableQL to run Grid Filter

 

- This example runs a Grid Filter which returns the most popular JavaScript packages
- The Grid Filter Toolbar has been [Pinned](https://www.adaptabletools.com/docs/ui-dashboard-tabs-toolbars/index.md#pinned-toolbars) so it sits above the Grid

- Click the Expand button (the 2 arrows) on the left of the Toolbar — or click the expression summary — to open the Grid Filter in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md), where the [Query Builder](https://www.adaptabletools.com/docs/ui-query-builder/index.md) and [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md) are available

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Basic Grid Filter',
  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['GridFilter'],
        },
      ],
    },

    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'github_watchers',
            'has_wiki',
            'updated_at',
            'license',
            'created_at',
            'topics',
            'pushed_at',
            'description',
            'open_issues_count',
          ],
          GridFilter: {
            Expression:
              '[language]="JavaScript" AND ([github_watchers] > 2000 OR [github_stars] > 14500)',
          },
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Named Queries

Grid Filters are typically created on the fly, evaluated immediately, and then cleared when no longer needed.

However, if required, Grid Filter Expressions can be named and saved in order to be re-used at a later date.

In this scenario it is called a **Named Query** and persisted into the `NamedQuery` section of Adaptable State.

It will then be available for loading at a later point in time (in this or future sessions).

See [Named Queries](https://www.adaptabletools.com/docs/handbook-named-queries/index.md) for full details on this topic

## Comparing Columns

One advantage of the Grid Filter over [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) is that it can be used to compare values in 2 Columns.

This can be done in both the Query Builder and the Expression Editor.

Only rows where **this** grid-filter expression is **true** are shown (the expression may compare **two or more columns** in one rule).

**Example: Comparing Column values with the Grid Filter**

Using Grid Filter to compare values in 2 Columns

 

- This example runs a Grid Filter which compares 2 sets of Columns
- The Expression is: `[closed_issues_count] > [closed_pr_count] AND [pushed_at] = [updated_at]`

- Open the Grid Filter in the Settings Panel (Expression Editor or Query Builder) to see how the Columns are compared

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Grid Filter - Column Comparison',
  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['GridFilter'],
        },
      ],
    },

    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'closed_issues_count',
            'closed_pr_count',
            'github_stars',
            'updated_at',
            'pushed_at',
            'license',
            'github_watchers',
            'created_at',
            'has_wiki',
            'open_issues_count',
          ],
          GridFilter: {
            Expression:
              '[closed_issues_count] > [closed_pr_count] AND [pushed_at] =[updated_at] ',
          },
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Grid Filter with Column Filters

The Grid Filter can be applied simultaneously with any [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md).

Only rows which pass **both** sets of evaluation will be displayed in the Grid

**Example: Grid Filter and Column Filters**

Applying a Grid Filter with Column Filters

 

- This example runs a Grid Filter as well as 4 Column Filters
- Only the 3 rows which pass **both** sets of evaluations are displayed

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Grid Filter with Column Filters',
  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['GridFilter'],
        },
      ],
    },

    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'github_watchers',
            'license',
            'pushed_at',
            'updated_at',
            'has_wiki',
            'created_at',
            'description',
            'open_issues_count',
            'topics',
          ],
          GridFilter: {
            Expression: '[license]="MIT License" OR [github_watchers] > 2000',
          },
          ColumnFilters: [
            {
              ColumnId: 'language',
              Expression: '[language] IN ("TypeScript", "JavaScript")',
            },
            {
              ColumnId: 'github_stars',
              Expression: '[github_stars] >= 5000 AND [github_stars] <= 90000',
            },
            {
              ColumnId: 'name',
              Expression: 'ENDS_WITH([name], ".js")',
            },
            {
              ColumnId: 'pushed_at',
              Expression: '[pushed_at] > DATE("2016-01-01")',
            },
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Managing the Grid Filter

The Grid Filter is accessible to both design-time and run-time users as follows:
- Developers can **define** a GridFilter (using the `GridFilter` property in the [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md) Definition)
- Developers can **configure** the GridFilter to match custom requirements
- Run-time users can **use** (ie. set, edit, clear, save, reload etc) the Grid Filter

See [Managing the Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter-managing/index.md) for more information

## UI Entitlements

The [UI Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md) behaviour for Grid Filter is as follows:

- `Full` - Grid Filters can be created, edited, cleared, suspended and saved; the UI components are available and display normally

- `Hidden` - No Grid Filter UI components are visible or available

- `ReadOnly` - The current Grid Filter Expression is visible in the Toolbar / Tool Panel, but it cannot be edited, cleared, suspended or saved

### FAQ

**Can we evaluate Grid Filters on the server?**
Yes, via the `evaluateAdaptableQLExternally` property in [Expression Options](https://www.adaptabletools.com/docs/technical-reference-expression/index.md) (see [Server Evaluation](https://www.adaptabletools.com/docs/adaptable-server-evaluation/index.md) for more details)

This option is only available if you are using the AG Grid **Client Side Row Model**

**Can we re-use the same Grid Filter Expression in different Modules - e.g. as a Plus / Minus Rule and a Report?**
Yes.  By saving the Grid Filter as a [Named Query](#named-queries), you can re-use the Expression for searching, styling, reports etc.

**Will the Grid Filter disappear if I run Quick Search or apply a Column Filter?**
No, all these different types of Searches are additive so they will all be applied individually if provided.
