Prepare Your Data

For a local Pivot, provide an array of records. Each record should describe one event, such as an order, with the fields needed to group and summarize it.

Start with one record shape

const orders = [
  { region: 'North', product: 'Headphones', quarter: 'Q1', sales: 200 },
  { region: 'North', product: 'Headphones', quarter: 'Q1', sales: 100 },
  { region: 'South', product: 'Speakers', quarter: 'Q2', sales: 200 },
];

region, product and quarter describe the order. sales is a number to calculate. A source record is sometimes called a fact; a descriptive grouping field is called a dimension.

The “Perfect” Pivot Source

Interactive example

Modeling Pivot data

Example for Modeling Pivot data

Flatten fact/dimension joins into a Pivot-ready row

The example loads when visible.

Reset

If your application stores product names separately from orders, join the required fields before passing records to a local Pivot. Keeping separate tables is valid application design; the local Pivot needs the fields it reads on each record.

const records = orders.map((order) => ({
  ...order,
  productName: productsById.get(order.productId)?.name ?? 'Unknown product',
}));

Value eligibility

Use raw finite numbers such as 1200.5, rather than formatted strings such as '$1,200.50'. Add a display format after calculation.

Decide what missing values mean. null, an empty string and 0 are different inputs; dataType: 'number' is metadata, not a validator. The aggregation guide explains defaults and explicit policies, including counts and distinct values.

Modeling Best Practices

1. Numeric vs. Categorical

Keep amounts numeric and labels readable. Keep identifiers stable when labels change, especially if users save reports.

2. Date Hierarchies

Provide explicit date parts when users should group by year, quarter or month:

const period = { year: 2026, quarter: 'Q2', month: 'April' };
// rows: ['year', 'quarter', 'month']

A raw date property does not automatically establish every hierarchy. Decide the intended timezone and calendar in your application before generating period fields.

3. Stability of Fields

Configuration refers to property names such as sales. If your API renames a property, update its field binding or remap the saved report.

Large Scale Modeling (Server-Side)

You do not need to download all orders when your backend can summarize them. In server-side mode, the application sends a report request and the backend returns grouped results. Your existing SQL or analytical service can implement that contract; a particular database is not required.

Next Steps

Create your first Pivot, then choose fields. Read OLAP concepts later if you want the analytical terminology.