AdapTable Version:

Framework:

Understanding Primary Keys

Summary

A Primary Key is required by AdapTable for cell identification purposes
It is the Id of a Column with guaranteed unique, unchanging values
If it cannot be provided, then an autogenerated key is used (but we strongly recommend that users provide one)

Primary Key Column

The Primary Key is set via the (mandatory) primaryKey property in Adaptable Options.

The value provided should either be:

an AG Grid Column - either the colId or field property

Caution
The column does not need to be visible but it does need to be specified
available as a data property in AG Grid's data source

Note

Without a Primary Key, AdapTable would not be able to uniquely identify cells for Cell Summary or Editing
Nor could it exactly specify in the Cell Changed or Adaptable State Changed Events which cells have been updated

primaryKey

Default: NONE: IS MANDATORY PROPERTY

String

Name of a Column in the Data Source guaranteed to contain unique values

It is highly recommended that this is provided.

The value provided does not need to be a column in the grid but must be in the data source.

If you absolutely cannot provide one, then leave blank and set autogeneratePrimaryKey to true.

const adaptableOptions: AdaptableOptions = {
  primaryKey: 'tradeId',
};

Key Uniqueness

It is important that Primary Key Column is one which guarantees to contain unique values.

Deep Dive

Why do Primary Keys have to be Unique?

Key Immutability

It is also important that values in the Primary Key Column do not change during the lifetime of the Application.

Deep Dive

Why do Primary Keys have to be Immutable?

Displaying Warnings

AdapTable logs a warning message to the console if the Primary Key provided is not an AG Grid Column.

Note

You can remove this warning by setting showMissingColumnsWarning to false in Column Options

showMissingColumnsWarning

Default: true

Boolean

Log warning to console if AdapTable cannot find a column

AdapTable, by default, logs a warning to the Console whenever a column referenced in Initial Adaptable State or Adaptable Options does not exist.

Set this property to false to suppress this warning.

// Don't display any warning messages in the Console if a referenced Column doesnt exist
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    showMissingColumnsWarning: false,
  },
};

This is particularly useful if the Primary Key value is provided in the Data Source but is not an AG Grid column.

Hint

For additional security you can also set showMissingPrimaryKeyAlert to true in Alert Options
This displays an Alert (with a Toast Notification) when no column in the grid which matches the Primary Key value

showMissingPrimaryKeyAlert

Default: false

Boolean

Shows Alert if Primary Key column is not present or incorrect

This property will cause AdapTable to display an Alert if the Primary Key column in Adaptable Options is missing or wrongly applied.

// Shows Alert if Primary Key column in Adaptable Options is not present or incorrect
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    showMissingPrimaryKeyAlert: true,
  },
};

Auto Generated Key

If it is absolutely not possible to provide a Primary Key column of your own, AdapTable can auto-generate one.

Important

Only use this option as a last resort if there is no column with unique values, as there are siginficant limitations
Auto-generated Keys cannot be used in Modules (e.g. Free Text Columns) which store cell details between sessions

Simply set autogeneratePrimaryKey property to true in Adaptable Options and AdapTable will create - and manage - its own internal Primary Key.

autogeneratePrimaryKey

Default: false

Boolean

Request AdapTable to create a generated Primary Key

Sets whether Adaptable should dynamically generate the Primary Key instead of using the primaryKey property.

Hint

If setting this property to true, ensure also to set primaryKey to an empty string

const adaptableOptions: AdaptableOptions = {
  autogeneratePrimaryKey: true,
  primaryKey: '',
};

Limitations

There are a few important limitations when using an auto generated Primary Key:

Modules which require persistable, consistent Primary Key values to save data are not available, including:
Live Data updates from Excel back to AdapTable (when using OpenFin) will not work (as Excel needs the column to be in the exported data)
If using an auto-generated key, the only safe way to load grid data, add Grid Rowsor Update Grid Rows is through AdapTable's Grid API; only use the following methods for any data manipulation you require:
- loadGridData - for initial (and replacement) data load
- addGridData - to add new rows
- updateGridData - to update rows
- deleteGridData - to remove rows
Note
- This restriction is required because AdapTable needs to intercept all data-related methods
- This will safely ensure that Primary Keys are propertly created and then kept correctly updated

Developer Guide

Using an auto generated Primary Key

Using an auto generated Primary Key - if it is absolutely necessary to do so - requires a couple of changes in the AdapTable setup:

const adaptableOptions: AdaptableOptions = {
  primaryKey: '', // set empty key
  userName: 'Demo User',
  adaptableId: 'Basic Setup',
  autogeneratePrimaryKey: true, // auto-generate key
  initialState: initialState,
};

Setting up Adaptable Options

There are 2 main changes that need to be made when setting up Adaptable Options:

provide no value to the primaryKey value
set the autogeneratePrimaryKey property to true

// Update the Grid Data using the Adaptable API
adaptableApi.gridApi.updateGridData([changedRow]);

Manage Row Data through AdapTable's Grid API

When you are using an auto generated Primary Key you need to provide row data via methods contained in Grid Api

Auto-Generated Primary Keys

Fork Fork

This Demo uses an Auto Generated Primary Key
It also has a Custom Button which updates the Price in the First Row - using the updateGridData function in Grid API

Expand to see how this was created

Try It Out

Open the Settings Panel and note that the Notes, Comments and FreeText Column Modules are not visible

FAQ

Can we provide a composite Primary Key? At the moment it is not possible to provide a Primary key composing more than one column. However this might be available in future versions of AdapTable.

AdapTable Resources

Read the Licensing page for more information
See the Integration Guides for the various AdapTable framework versions:

PreviousAG Grid Modules NextAdapTable State Key

Framework:

Understanding Primary Keys

Summary

Primary Key Column

Caution

Note

primaryKey

Key Uniqueness

Deep Dive

Why do Primary Keys have to be Unique?

Key Immutability

Deep Dive

Why do Primary Keys have to be Immutable?

Displaying Warnings

Note

showMissingColumnsWarning

Hint

showMissingPrimaryKeyAlert

Auto Generated Key

Important

autogeneratePrimaryKey

Hint

Limitations

Note

Developer Guide

Using an auto generated Primary Key

Expand to see how this was created

FAQ

AdapTable Resources