Initializing help system before first use

# Using VDL Action Group-By

The VDL Action `vdl-action-group-by` groups data by the key at a given position.

The `vdl-action-group-by` Action can be used in conjunction with other VDL Data Actions to get and aggregate entity data, filter it, and group it by a selected data key. The Actions can be used to dynamically fetch, save, group, filter, aggregate, label, and display data.

The `vdl-action-group-by` Action takes one or more keys and groups entity data according to those keys.

Data to be grouped must be formatted correctly. Each object in the data must have a key property. Key properties must be an array of primitives.

Group By single dimension

The `vdl-action-group-by` Action creates a new object (group) for each key. The object contains two properties, the key, and an array containing all of the rows with the unique key at the designated set position.

For example, when grouping the following data, there is a two-dimensional key:

- set-position 0:`['revenue', 'cost']`
- set-position 1: `['q-1', 'q-2', 'q-3', 'q-4']`

    <script>
    const data = [
            {key: ['revenue', 'q-1'], value: 105},
            {key: ['revenue', 'q-2'], value: 505},
            {key: ['revenue', 'q-3'], value: 905},
            {key: ['revenue', 'q-4'], value: 541},
            {key: ['cost', 'q-1'], value: 310},
            {key: ['cost', 'q-2'], value: 60},
            {key: ['cost', 'q-3'], value: 360},
            {key: ['cost', 'q-4'], value: 521}
        ];
    </script>

When grouped by set-position 0 the data should appear as shown below:
When grouped by set-position 1, the data will be grouped into four sections, q-1, q-2, q-3, and q-4 .
To group by a single dimension you must define the data to be used, and the set-position to group by. This example uses the data defined above, and stores the result in the VDL Var, before defining VDL buttons to change which set-position is used to group the data.

    <vdl-var name="exampleData" value="=[]"></vdl-var>

    <vdl-action-group name="example">
        <vdl-action-group-by data="=data" set-position="=value"></vdl-action-group-by>
        <vdl-action-set-var var="exampleData"></vdl-action-set-var>
    </vdl-action-group>

    <vdl-button label="Group source data by set-position 0" value="0" vdl-event="click:actions.example"></vdl-button>
    <vdl-button label="Group source data by set-position 1" value="1" vdl-event="click:actions.example"></vdl-button>

Data is returned as an array of objects. Each object has a key and values property. The key will be a primitive and the values property will be an array containing the data objects for that group.

Group By multiple dimensions

The `vdl-action-group-by` Action can also be used to group data by multiple keys. When grouping by multiple keys the object will contain an array of the keys used to group the data, and an array containing all the rows with the unique key at the designated set-position.

When defining multiple keys to group the data by, you must enter the set-position as an array, for example:

    <vdl-action-group-by data="=vars.example1Data" set-position="=[0,1]"></vdl-action-group-by>

Using default keys

You can ensure that the results of `vdl-action-group-by` will always contain specific keyed groups or objects by using the `default-keys` attribute. Keys that are passed to `vdl-action-group-by` will always be displayed, but `default-keys` can be used to force a key to be displayed even if there are no data rows containing that key to be displayed.

If keys passed in `default-keys` exist in the data, they will not be duplicated.

Default keys are defined as shown below:

    <vdl-action-group-by data="=example2Data" set-position="1" default-keys="=[1,2,3,4,5]"></vdl-action-group-by>

Data is returned as an array of objects. Each object has a key and values property. The key will be an array of primitives, and the values property will be an array containing the data objects for that group.
Parent Topic VDL Actions

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.