# Pivot analysis

Pivoting divides source orders into row, column, and value axes to create a cross-tabulation. Unlike collapsible row groups, unique values such as statuses become new result columns.

Canonical: https://grid.syidax.com/docs/features/pivot/

<a id="understand"></a>

## How it works and when to use it

For example, teams form rows, regions form columns, and quantities are summed. Prepare all three axes before enabling pivotMode and choose aggregation for each numeric field.

Using this feature in a product requires the Pro package and a valid license. Matching setting names do not enable Pro features in Community.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Quantity by team × region

Apply to a table whose source data contains team, region, and quantity.

```javascript
grid.pivotRowGroupColumns = ['team'];
grid.pivotColumns = ['region'];
grid.pivotValueColumns = ['quantity'];
grid.pivotAggFuncs = { quantity: 'sum' };
grid.pivotMode = true;
```

Verify the result: A result column appears for each region, containing each team's quantity total. Source order rows are not modified.

<a id="example-2"></a>

## Example 2. Position subtotals and grand totals

With multiple row-axis levels, choose where intermediate and overall totals appear.

```javascript
grid.pivotRowGroupColumns = ['region', 'team'];
grid.pivotSubtotals = 'bottom';
grid.pivotGrandTotal = 'top';
grid.pivotPanelShow = 'always';
```

Verify the result: Read subtotals below expanded child groups and see the grand total at the top.

<a id="example-3"></a>

## Example 3. Inspect generated result columns

Before connecting charts or export, read the actual result-column identifiers and current combination state.

```javascript
console.log(await grid.getPivotSecondaryColumns());
console.log(await grid.getPivotCombinationReport());
```

Verify the result: Use returned identifiers instead of region labels as column IDs. Server pivoting uses getServerPivotResultColumns() and a separate server-response contract.

<a id="pitfalls"></a>

## Combining features and troubleshooting

Do not guess precedence among row grouping, trees, and pivoting. Check active features and restrictions in the combination report first.

Do not assume source filters affect pivot aggregation identically. Verify the current aggregation scope and results, and prepare pivot input data first if needed.

<a id="related-api"></a>

## APIs used by this feature

- [pivotMode](https://grid.syidax.com/docs/options/pivotMode.md) — Enables pivot aggregation across row, column, and value axes. Configure all three axes too.
- [pivotRowGroupColumns](https://grid.syidax.com/docs/options/pivotRowGroupColumns.md) — Fields forming the left-hand row axis of pivot results.
- [pivotColumns](https://grid.syidax.com/docs/options/pivotColumns.md) — Fields whose distinct values expand into pivot result columns at the top.
- [pivotValueColumns](https://grid.syidax.com/docs/options/pivotValueColumns.md) — Value fields aggregated at each pivot intersection.
- [pivotAggFuncs](https://grid.syidax.com/docs/options/pivotAggFuncs.md) — Aggregate function names for each value field. Supports built-in and registered custom functions.
- [pivotSubtotals](https://grid.syidax.com/docs/options/pivotSubtotals.md) — Hides nested pivot subtotals or positions them above or below expanded groups.
- [pivotGrandTotal](https://grid.syidax.com/docs/options/pivotGrandTotal.md) — Hides pivot grand totals or positions them at the top or bottom.
- [pivotPanelShow](https://grid.syidax.com/docs/options/pivotPanelShow.md) — Shows the pivot panel always, only in pivot mode, or never.
- [pivotPanel](https://grid.syidax.com/docs/options/pivotPanel.md) — Compatibility boolean for the pivot panel. true corresponds to pivotPanelShow: always.
- [getPivotCombinationReport](https://grid.syidax.com/docs/methods/getPivotCombinationReport.md) — Reads activation, priority, and restriction decisions for the current combination of pivoting and other features.
- [getPivotSecondaryColumns](https://grid.syidax.com/docs/methods/getPivotSecondaryColumns.md) — Reads the identity model of result columns created by the active client pivot, or null when no pivot is active.
- [setPivotColumns](https://grid.syidax.com/docs/methods/setPivotColumns.md) — Replaces the pivot column axis through the validated update path and returns success.
- [setValueColumns](https://grid.syidax.com/docs/methods/setValueColumns.md) — Replaces the pivot value axis through the validated update path and returns success.
- [pivotPanelChanged](https://grid.syidax.com/docs/events/pivotPanelChanged.md) — Emitted when axes change in the pivot panel. Inspect the changed axis and current pivot state.
- [pivotChanged](https://grid.syidax.com/docs/events/pivotChanged.md) — Reports pivot configuration changes. Avoid duplicate saves from subscribing to both compatibility and panel events.
- [pivotModeChanged](https://grid.syidax.com/docs/events/pivotModeChanged.md) — Emitted when pivot mode is enabled or disabled.
- [pivotCombinationConflict](https://grid.syidax.com/docs/events/pivotCombinationConflict.md) — Emitted when pivot settings conflict with other features. Adjust app options based on the actual compatibility decision.
- [pivotColumnsChanged](https://grid.syidax.com/docs/events/pivotColumnsChanged.md) — Emitted when the pivot result column model changes. Update chart and export code using previous result column IDs.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/pivot) — The guide describes which interactions are available to try.