# Pivot Overview
URL: https://pro.rv-grid.com/guides/pivot/
Source: src/content/docs/guides/pivot/index.mdx
Description: Learn the Pivot mental model, when to use it, and how to build your first RevoGrid Pivot.
Pivot turns a flat fact table into an analytical view. You choose which fields define the row hierarchy, which fields define generated columns, and which fields become aggregated measures. RevoGrid stays responsible for rendering and interaction, while Pivot builds the grouped rows, generated headers, totals, and summary cells.

For raw type signatures, see [Pivot API](/api/pivot/) and [Pivot Config API](/api/pivot-config/). Use this guide set for behavior, defaults, and how the parts work together.

## When To Use Pivot

Use Pivot when your source rows represent detailed facts such as orders, transactions, tickets, or events, and users need to answer questions like:

- "Sales by region and quarter"
- "Count of incidents by team and priority"
- "Average margin by category and month"
- "Grand totals and subtotals across multiple hierarchies"

Use a normal grid when users mainly inspect or edit row-level records. Use Pivot when users need grouped analytical summaries.

## Core Vocabulary

- `dimension`: A field that can be placed on the row axis, column axis, or used as a value source.
- `row field`: A dimension listed in `rows`. It creates the vertical hierarchy.
- `column field`: A dimension listed in `columns`. It creates generated headers.
- `value`: A measure listed in `values`. It is aggregated into Pivot cells.
- `generated row`: A synthetic row produced by Pivot, not a raw input row.
- `generated column`: A synthetic column or column group produced by Pivot.
- `subtotal`: A summary for one intermediate branch of a hierarchy.
- `grand total`: A summary across the full filtered result.

## Mental Model

Client-side Pivot follows this shape:

```txt
source rows
  -> group by rows / columns
  -> aggregate values
  -> generate row hierarchy
  -> generate column hierarchy
  -> render with RevoGrid
```

Server-side Pivot keeps the same public config, but the aggregation step moves behind a remote engine boundary:

```txt
source rows
  -> analytical engine
  -> visible analytical window
  -> RevoGrid
```

That means the same concepts stay in place even when the data becomes too large for full client-side materialization.

## Conceptual Foundations

If you are new to Pivot tables or Business Intelligence (BI) concepts, we recommend starting with these conceptual guides:

- [What Is Pivot?](/guides/pivot/what-is-pivot/): The basic mental model of transforming flat data.
- [What is an OLAP Cube?](/guides/pivot/olap-cube-concepts/): Understanding multidimensional analysis and core operations.
- [Data Modeling for Pivot](/guides/pivot/data-modeling/): How to structure your facts and dimensions for the best results.

## First Working Pivot

1. Install the Enterprise package.

   ```bash
   pnpm add @revolist/revogrid-enterprise
   ```

2. Import the plugin and any aggregators you want to expose.

   ```ts
   import {
     PivotPlugin,
     commonAggregators,
     type PivotConfig,
   } from '@revolist/revogrid-enterprise';
   ```

3. Register `PivotPlugin` on the grid.

   ```ts
   grid.plugins = [PivotPlugin];
   ```

4. Define a `PivotConfig`.

   ```ts
   const pivot: PivotConfig = {
     dimensions: [
       { prop: 'region', name: 'Region' },
       { prop: 'quarter', name: 'Quarter' },
       {
         prop: 'sales',
         name: 'Sales',
         aggregators: {
           ...commonAggregators,
         },
       },
     ],
     rows: ['region'],
     columns: ['quarter'],
     values: [{ prop: 'sales', aggregator: 'sum' }],
   };
   ```

5. Apply it through the direct `pivot` binding.

   ```ts
   grid.pivot = pivot;
   ```

   `additionalData.pivot` is still observed for legacy integrations, but new code should bind `pivot` directly.

## How To Read A PivotConfig

```ts
const pivot: PivotConfig = {
  dimensions: [...],
  rows: ['region', 'rep'],
  columns: ['year', 'quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  collapsed: true,
};
```

- `dimensions` describes the reusable field metadata.
- `rows` defines the row hierarchy from left to right.
- `columns` defines the generated header hierarchy from left to right.
- `values` defines which measures are aggregated in each visible cell.
- `totals` enables grand totals and subtotals.
- `collapsed` enables grouped row drill-down when the row hierarchy has multiple levels.
- `groupAggregations` makes grouped Pivot rows show aggregate values across generated metric columns.

## What RevoGrid Pivot Owns

When Pivot is active, `PivotPlugin` temporarily owns:

- the rendered `source`
- the rendered `columns`
- optional `pinnedBottomSource` for grand totals
- grouped-row metadata used for drill-down

When Pivot is cleared, the plugin restores the original source, columns, grouping, and pinned totals.

## Feature Map

- Client-side Pivot rows, columns, values, totals, and drill-down are implemented.
- Client-side grouped row aggregates are implemented through `pivot.groupAggregations`.
- `valuesOnRows`, flat headers, and the drag-and-drop configurator are implemented.
- Server-side Pivot exposes a first-class remote engine/store contract and plugin integration.
- The docs below describe the current implementation in `packages/enterprise/plugins/pivot` and `packages/enterprise/plugins/pivot-config`.

## Recommended Reading Order

1. [What Is Pivot?](/guides/pivot/what-is-pivot/)
2. [What is an OLAP Cube?](/guides/pivot/olap-cube-concepts/)
3. [Data Modeling for Pivot](/guides/pivot/data-modeling/)
4. [Dimensions](/guides/pivot/dimensions/)
5. [Aggregations](/guides/pivot/aggregations/)
6. [Configuration Reference](/guides/pivot/configuration-reference/)
7. [Totals](/guides/pivot/totals/)
8. [Values On Rows](/guides/pivot/values-on-rows/)
9. [Drill-Down](/guides/pivot/drilldown/)
10. [Sorting And Filtering](/guides/pivot/sorting-filtering/)
11. [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
12. [Configurator](/guides/pivot/configurator/)
13. [Field Panel](/guides/pivot/field-panel/)
14. [Server-Side Pivot](/guides/pivot/server-side/)
15. [Caching And Cache Keys](/guides/pivot/caching/)
16. [OLAP Best Practices](/guides/pivot/olap-best-practices/)
