Vue Data GridClient-Side Data - Transaction Updates

Transaction Updates allow large numbers of rows in the grid to be added, removed or updated in an efficient manner. Use Transaction Updates for fast changes to large datasets.

Transaction Update API

A transaction object contains the details of what rows should be added, removed and updated. The grid API applyTransaction(transaction) takes this transaction object and applies it to the grid's data.

The result of the applyTransaction(transaction) is also a transaction, however it is a list of Row Nodes that were added, removed or updated. Both types of transactions look similar, but the difference is the data type they contain.

• Row Data Transaction: Contains Row Data, the data that you are providing to the grid.
• Row Node Transaction: Contains Row Nodes, the grid-created objects that wrap row data items.

For each data item in a Row Data Transaction there will typically be a Row Node in Row Node Transaction wrapping that data item. The only exception is for edge cases, for example you tried to delete or update a data item that didn't exist.

Example: Updating with Transaction

The example applies transactions in different ways and prints the results of the call to the console. The following can be noted:

• Add Items: Adds three items.
• Add Items addIndex=2: Adds items at index 2.
• Update Top 2: Updates the price on the first 2 rows in the list.
• Remove Selected: Removes all the selected rows from the list.
• Get Row Data: Prints all row data in the grid to the console.
• Clear Data: Sets the data in the grid to an empty list.

Identifying Rows for Update and Remove

When passing in data to be updated or removed, the grid will be asking:

"What row do you mean exactly by this data item you are passing?"

There are two approaches you can take: 1) Providing Row IDs, or 2) Using Object References.

• Providing Row IDs (Faster)

  If you are providing Row IDs using the grid callback getRowId() then the grid will match data provided in the transaction with data in the grid using the key.

  For updating rows, the grid will find the row with the same key and then swap the data out for the newly provided data.

  For removing rows, the grid will find the row with the same key and remove it. For this reason, the provided records within the remove array only need to have a key present.

<ag-grid-vue
    :getRowId="getRowId"
    /* other grid options ... */>
</ag-grid-vue>

this.getRowId = (params) => params.data.employeeId;

const myTransaction = {
    add: [
        // adding a row, there should be no row with ID = 4 already
        {employeeId: '4', name: 'Billy', age: 55}
    ],   
    update: [
        // updating a row, the grid will look for the row with ID = 2 to update
        {employeeId: '2', name: 'Bob', age: 23}
    ],
    remove: [
        // deleting a row, only the ID is needed, other attributes (name, age) don't serve any purpose
        {employeeId: '5'}
    ]
}

• Using Object References (Slower)

  If you do not provide Row IDs for the rows, the grid will compare rows using object references. In other words when you provide a transaction with update or remove items, the grid will find those rows using the === operator on the data that you previously provided.

  When using object references, note the following:

  1. The same instance of the row data items should be used. Using another instance of the same object will stop the grid from making the comparison.

  2. Using object references for identification will be slow for large data sets, as the grid has no way of indexing rows based on object reference.

Although using object references is slower, this will only be an issue if working with large datasets (thousands of rows).

Example: Updating with Transaction and Groups

When using transactions and grouping, the groups are kept intact as you add, remove and update rows. The example below demonstrates the following:

• Add For Sale: Adds a new item to 'For Sale' group.
• Add In Workshop: Adds a new item to 'In Workshop' group.
• Remove Selected: Removes all selected items.
• Move to For Sale: Move selected items to 'For Sale' group.
• Move to In Workshop: Move selected items to 'In Workshop' group.
• Move to Sold: Move selected items to 'Sold' group.
• When moving items, the grid animates the rows to the new location with minimal DOM updates.
• Get Row Data: Prints all row data to the console.

Localised Changes in Grouped Data

When you apply a transaction to grouped data, the grid will only re-apply grouping, filtering and sorting to the impacted data.

For example, suppose you have the grid with its rows grouped into 10 groups and a sort is applied on one column. If a transaction is applied to update one row, then the group that row sits within will be re-sorted as well as the top level group (as aggregations could impact values at the top level). All of the other 9 groups do not need to have their sorting re-applied.

Deciding what groups need to be operated on within the grid is called Changed Path Selection. After the grid applies all adds, removes and updates from a transaction, it works out what groups were impacted and only executes the required operations on those groups. The groups that were impacted include each group with data that was changed, as well as all parents of changed groups all the way up to the top level.

The example below demonstrates Changed Path Selection. The example is best viewed with the dev console open so log messages can be observed. Note the following:

• The 'Distro' column is sorted with a custom comparator. The comparator records how many times it is called.

• The Value column is aggregated with a custom aggregator. The aggregator records how many times it is called.

• When the example first loads, all the data is set into the grid which results in 171 aggregation operations (one for each group), approximately 24,000 comparisons (for sorting all rows in each group, the number of sorts differ slightly depending on the data values which are random in this example) and 10,000 filter passes (one for each row). The number of milliseconds to complete the operation is also printed (this value will depend on your hardware).

• Select a row and click Update, Delete OR Duplicate (duplicate results in an add operation). Note in the console that the number of aggregations, compares and filters is drastically fewer. The total time to execute is also drastically less.

Suppress Model Updates

To perform update transactions and prevent the grid from automatically reprocessing grouping, filters, aggregation and sorting, enable the suppressModelUpdateAfterUpdateTransaction grid option. This can be helpful to prevent data moving while the user is in an edit state for a row.

Note that this property is only used when transactions are applied that only have updates. If the transaction contains any adds or removes, the sorting, filtering and grouping will always be applied.

To trigger the the Client-side Row Model to refresh, use the Grid API refreshClientSideRowModel(startingStage). As the stages are sequential, the Client-side Row Model will refresh at the provided stage and then all the stages after it will also refresh. In order, these stages are: group, filter, pivot, aggregate, sort, filter aggregates, and map.

In the example above suppressModelUpdateAfterUpdateTransaction=true. Note the following:

1. When data is updated, using the Apply Transaction button, the grid does not re-execute sorting or filtering.
2. After data is updated, hitting Update Model triggers the grid to sort and filter using refreshClientSideRowModel('filter').

Delta Sorting

While using transactions to modify the grids data model, the default behaviour when a row is modified is for the grid to sort the modified row as well as every sibling into a new ordered list.

The deltaSort option is a performance enhancement which may (depending upon your configuration) provide a faster experience by instead:

• Filtering deleted and updated rows from the previously sorted data set
• Only sorting the changed and added rows together in a new list
• Merging the cleaned and changes lists to produce a new sorted data set

It is possible that, if using transactions, enabling this feature may provide a performance boost to your application. Delta sort may be beneficial to you if:

• Your data has a large amount of rows in each row group (or a large number of rows with no grouping) and comparatively small transactions
• You're sorting by a large number of columns simultaneously

Some caveats also exist which may make delta sorting slower in your application if:

• Your data set is small compared to the size of your transactions
• You have a large number of groups containing small numbers of rows.

In the below example two buttons have been provided, one using delta sort and one without. When clicked they will use a transaction to insert one row and update one existing row on the initial dataset of 100,000 rows.