# Bulk Update

Canonical page: https://www.adaptabletools.com/docs/handbook-editing-bulk-update

- Bulk Update replaces, via a single action, the cell value in multiple cells
- All the cells will receive the same new value
- The new value can either be one that already exists in the column or an entirely new one

Bulk Update replaces, via a single action, the cell value in multiple cells in one (editable) Column.

All the cells that are updated will display **the same new value**.

Bulk Update differs from [Smart Edit](https://www.adaptabletools.com/docs/handbook-editing-smart-edit/index.md) in that it **replaces**, rather than updates, the existing cell value

The **replacement** value can either be one that already exists in the column or an entirely new one.

## Using Bulk Update

Bulk Update can be applied on **text**, **numeric** and **date** columns. 

Bulk Updates can be applied in numerous places in the AdapTable UI:

- Bulk Update [Toolbar](https://www.adaptabletools.com/docs/ui-dashboard-tabs-toolbars/index.md) - available in [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md)
- Bulk Update [Module Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel-module-tool-panels/index.md) - available in [AdapTable Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md)
- Bulk Update page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md) — available via the [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md)
- Bulk Update [Status Bar](https://www.adaptabletools.com/docs/technical-reference-status-bar/index.md) (displays a Button that opens the Bulk Update page in the Settings Panel)

### Applying a Bulk Update

There are various Bulk Update UI controls, but they all operate in a very similar fashion:

Bulk Update requires that cells are selected from a single editable column.

The Column's Data Type can be `numeric`, `string`, or `date`.

Right-click in the [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) to open the Bulk Update page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md) (or click the Bulk Update [Status Bar](https://www.adaptabletools.com/docs/technical-reference-status-bar/index.md) button)

Alternatively you can apply a Bulk Update directly from:
- the [Bulk Update Toolbar](https://www.adaptabletools.com/docs/ui-dashboard-tabs-toolbars/index.md) (in the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md))
- the [Bulk Update Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel-module-tool-panels/index.md) (in the [AdapTable Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md))

The Bulk Update control contains a Dropdown with a distinct list of values for the Column.

The values in the dropdown can be provided by developers - see [Providing Custom Column Values when Editing](https://www.adaptabletools.com/docs/handbook-editing-custom-column-values/index.md) for full details

You can now either:

- Select an existing value from the Dropdown
- Type in a new value (and click the "Create" button)

Adaptable will perform validation on the proposed Bulk Update.

The *Apply Bulk Update* button changes colour to tell you if the edit will break validation.

A Preview Results table shows which of the proposed edits break Validation. In the Toolbar and Tool Panel, click the *Preview Results* button to open the Bulk Update page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md), where this table is displayed.

If all the Edits are invalid, the *Apply Bulk Update* button is disabled

Click the *Apply* button (if validation succeeded) to apply the Bulk Update.

**Example: Bulk Update**

Updating numerous cells in one operation

- Select editable cells in a **single column** (text, numeric, or date), choose a value in the Bulk Update toolbar, then apply

- Select a value in the Bulk Update toolbar and press the Green tick to update the selected cells

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
  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: 'Bulk Update',
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['BulkUpdate'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['BulkUpdate'],
        },
      ],
    },
    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,
        },
      ],
    },
  },
};
```
**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo} from '@adaptabletools/adaptable';

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  setTimeout(() => {
    adaptableApi.gridApi.selectCellRange({
      columnIds: ['language'],
      rowIndexStart: 0,
      rowIndexEnd: 10,
    });
  }, 10);
};
```

## Validating Bulk Update

AdapTable will check all [Data Validation Rules](https://www.adaptabletools.com/docs/handbook-validating-client/index.md) before applying a Bulk Update.

The *Apply Bulk Update* button colour indicates the results of the validation check:

| Proposed Edits   | Button Colour / Type       | *Apply Bulk Update* Button Behaviour                   |
| ---------------- | -------------------------- | ------------------------------------------------------ |
| All are Valid    | Success (default is green) | Button is fully enabled                                |
| Some are Invalid | Warning (default is amber) | Button is enabled but **only** valid edits are applied |
| All are Invalid  | Error (default is red)     | Button is disabled and the operation is not accessible |

In addition AdapTable will display a *Preview Results* table which will indicate — and provide details — of which proposed edits break a Validation Rule.

In the Bulk Update [Dashboard Toolbar](https://www.adaptabletools.com/docs/ui-dashboard-tabs-toolbars/index.md) and [Module Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel-module-tool-panels/index.md), click the *Preview Results* button to open the Bulk Update page in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md), where the table is displayed

**Example: Bulk Update Validation**

Bulk Update validating proposed edits

- This example shows what happens when trying to apply a Bulk Update which breaks Validation
- We have created a [Data Validation Alert](https://www.adaptabletools.com/docs/handbook-alerting-validation/index.md) that the `Language` column value cannot be "Python"
- Trying to enter "Python" in Bulk Update for Language column will not be allowed and the table will display all the failed validations

- Enter "Python" in the dropdown in the Bulk Update Toolbar as a *new value* and see the validation results immediately error

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
  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: 'Bulk Update Validation',
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['BulkUpdate'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['BulkUpdate'],
        },
      ],
    },
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-language',
          Scope: {
            ColumnIds: ['language'],
          },
          Rule: '[language] = "Python"',
          AlertProperties: {
            PreventEdit: true,
            DisplayNotification: true,
          },
          MessageType: 'Error',
          MessageText: 'Language cannot be "Python"!',
        },
      ],
    },
    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,
        },
      ],
    },
  },
};
```
**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo} from '@adaptabletools/adaptable';

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  setTimeout(() => {
    adaptableApi.gridApi.selectCellRange({
      columnIds: ['language'],
      rowIndexStart: 0,
      rowIndexEnd: 10,
    });
  }, 10);
};
```

## Custom Column Values

By default the Bulk Update component will automatically display a list of the **distinct** values in that column.

However it is possible to provide a bespoke list of items to display instead, via the `customEditColumnValues` property in [Edit Options](https://www.adaptabletools.com/docs/technical-reference-editing/index.md).

See [Providing Custom Column Values when Editing](https://www.adaptabletools.com/docs/handbook-editing-custom-column-values/index.md) for more information and a demo

### FAQ

**Can I perform a Bulk Update on any column?**
Yes, well most. Bulk Update can be performed on text (string), numeric and date columns.

**Can I perform Bulk Update on a readonly column?**
No, Bulk Update only applies on editable columns.

**How do Module Entitlements affect Bulk Update?**
When the Bulk Update module is `Hidden`, UI is unavailable (same as other action-only modules). There is no separate read-only mode for Bulk Update objects.

**Can I perform a Bulk Update across more than one column?**
No, like [Smart Edit](https://www.adaptabletools.com/docs/handbook-editing-smart-edit/index.md), Bulk Update works on only one column at a time.

**Can I choose to enter a value that is not currently in the column?**
Yes, you can enter either an existing column value or an entirely new one.

**I do not want all the current values in the Column to be available in the Bulk Update dropdown?**
You can [provide custom values](https://www.adaptabletools.com/docs/handbook-editing-custom-column-values/index.md) to be displayed in the Bulk Update control.
