---
id: "packages/active-charts/all-exports/data-grouping-options"
title: "Data grouping options"
description: "AggregationMethod, DataGroupingOptions, GroupingUnit, GroupingUnitTable and 3 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/data-grouping-options"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:data-grouping-options"
---

# Data grouping options

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## Functions, hooks and constants

**GROUP_META_KEY**: `"__groupMeta"`

Internal sentinel field name used to attach `GroupMeta` to a synthetic
`ChartDatum`. Consumers should read it via the typed `groupMeta`
property on tooltip data; this constant exists for the grouping engine.

## Types

**AggregationMethod**

```ts
type AggregationMethod =
  'average' | 'sum' | 'open' | 'high' | 'low' | 'close' | 'ohlc' | 'range';
```

Aggregation method applied to the value of a single-valued series within
each group (line, area, bar, scatter). Error-bar bounds and bubble size
follow the same method; a method that picks one row takes them from that
row.

- `average` — arithmetic mean (default for line, area and scatter).
- `sum` — total of all values in the group (default for bar).
- `open` — first value in the group.
- `high` — maximum value.
- `low` — minimum value.
- `close` — last value.
- `ohlc`, `range` — the role bundles of price and range series. Those
series are always grouped role by role (first open, highest high,
lowest low, last close; lowest low, highest high) under their own field
names, whatever the method. On a single-valued series a bundle has no
meaning: the series keeps the default of its type, with a development
diagnostic.

**DataGroupingOptions**

```ts
interface DataGroupingOptions {
  enabled?: boolean;
  units?: GroupingUnitTable;
  approximation?: AggregationMethod;
  groupPixelWidth?: number;
  anchor?: 'start' | 'middle' | 'end';
  forced?: boolean;
}
```

**GroupingUnit**

```ts
type GroupingUnit =
  | 'millisecond'
  | 'second'
  | 'minute'
  | 'hour'
  | 'day'
  | 'week'
  | 'month'
  | 'quarter'
  | 'year';
```

Time-based unit for grouping data points into calendar-aligned buckets.
UTC-first: bucket boundaries are computed against UTC calendar fields,
not the browser's local timezone.

**This is zoom-level downsampling, not business calendar aggregation.**
A bucket boundary here is a rendering decision on a machine
timeline; a business day, week or month boundary belongs to an owner's time
zone and is computed SERVER-side, with the resulting buckets handed to the
chart ready to draw. See `bucketStart` in `core/data/grouping/bucket.ts` for
the full boundary and the worked examples.

**GroupingUnitTable**

```ts
type GroupingUnitTable = ReadonlyArray<
  readonly [GroupingUnit, ReadonlyArray<number>]
>;
```

Per-unit table of allowed multipliers. The auto-unit selector picks the
smallest `unit × multiple` whose interval covers ≥ `groupPixelWidth`
pixels at the current zoom level. Smallest unit first.

**GroupMeta**

```ts
interface GroupMeta {
  unit: GroupingUnit;
  multiple: number;
  start: number;
  end: number;
  count: number;
  raw: {
    min: number;
    max: number;
    sum: number;
  };
}
```

Metadata attached to each synthetic group point. Tooltip renderers and
custom formatters can read this to display the interval, the count of
source points, and the raw min/max/sum without re-aggregating.

**SeriesDataGroupingOverride**

```ts
interface SeriesDataGroupingOverride {
  enabled?: boolean;
  approximation?: AggregationMethod;
}
```

Per-series data grouping override. `false` (or `enabled: false`) keeps
this series' values unaggregated. The rows are shared by every series, so
an opt-out keeps the whole chart ungrouped (one chart-wide policy,
ADR-034), with a development diagnostic.