Skip to content
Barchart Barchart HTML5 Chart

Aggregation action

Use this action with change({ id: 'Aggregation', context }).

Context

  • id?: Get | Update (Update is assumed if omitted)
  • aggregation fields for Update:
    • unit: Tick | Intraday | Day | Week | Month | Quarter | Year (Day by default)
    • size: positive integer (1 by default)
    • spec: None | Nearest | Continue | PerCount | PerVolume | PerRange | PerSeconds | TopOfBook (None by default)
    • isContractVolume: boolean (false by default)
    • dividendsAdjust: boolean (false by default)
    • backAdjust: boolean (false by default)
    • daysToExpiration: integer from 0 to 60 (1 by default)
    • contractRoll: expiration | combined (combined by default)

Aggregation fields

unit selects the bar period. Intraday uses size as minutes, so { unit: "Intraday", size: 5 } means 5-minute bars. Day, Week, Month, Quarter, and Year are end-of-day periods. Tick uses tick data; with spec: "None" it represents raw trade ticks.

size is the amount of the selected unit included in one bar. It is used directly for Tick, Intraday, and Day aggregations. For Week, Month, Quarter, and Year, the chart treats the aggregation as one calendar week, month, quarter, or year.

spec adds specialized behavior to the selected unit:

  • None: normal aggregation for the selected unit.
  • Nearest: for futures, request the nearest-contract series. For end-of-day data, this maps to the historical server’s nearest daily, weekly, monthly, quarterly, or yearly records. For intraday futures, this uses nearby minute data.
  • Continue: for futures end-of-day data, request a continuation series. The historical server defines continuation records as the same contract month across different contract years.
  • PerCount: for Tick, build custom OHLC bars from raw trade ticks, using size trades per bar.
  • PerVolume: for Tick, build custom OHLC bars from raw trade ticks, using cumulative trade size to decide when to start a new bar.
  • PerSeconds: for Tick, build custom OHLC bars from raw trade ticks, using size seconds per bar.
  • PerRange: for Intraday, build custom range bars. size is multiplied by the symbol metadata minimum price movement to determine the price range.
  • TopOfBook: for Tick, fetch historical quote rows with best bid, best ask, and bid/ask sizes instead of trade ticks.

The PerCount, PerVolume, and PerSeconds specs are client-side custom tick aggregations. The chart fetches raw tick trades, then rebuilds OHLC bars from the tick Last price and TradeSize.

  • PerCount starts a new bar after size trades. The bar timestamp comes from the first trade in that custom bar.
  • PerVolume starts a new bar when the next trade would bring the running trade-size total to size or higher. Oversized trade-size remainders are carried forward, and the builder starts a new bar at calendar day boundaries so bars do not span days.
  • PerSeconds groups trades into size-second windows. Bar timestamps are aligned to size-second boundaries, and trades update the current bar until they fall outside that window.

PerRange is also built by the chart instead of by the historical server. For historical data, the chart requests 1-minute intraday OHLC rows and builds range bars from those rows; for live updates, incoming trades update the range builder. The range size is size * minMovement, where minMovement comes from the symbol metadata. A range bar continues while price remains within that range. When price crosses the upper or lower range boundary, the builder closes the current bar at the boundary and starts the next range bar.

isContractVolume affects futures volume on end-of-day aggregations. true requests contract volume for the individual contract. false requests total volume across open contracts. For aggregate periods such as weekly, monthly, or yearly, the historical server returns average volume for the period.

dividendsAdjust affects stock data. true requests dividend-adjusted data from the historical server. false requests data without dividend adjustment.

backAdjust affects multi-contract futures series. When enabled, the historical server adjusts the contracts in the series by the roll gap between the current contract close and previous contract close on the day of the switch. It applies only to multi-contract futures queries and is ignored for other queries.

daysToExpiration affects futures roll timing. It is the number of calendar days before contract expiration when a multi-contract series switches to the next contract. Valid values are 0 through 60; 0 rolls on the expiration day. If omitted, the historical server defaults to 1, meaning each contract runs through the day before expiration. It applies only to multi-contract futures queries and is ignored for other queries.

contractRoll affects futures multi-contract nearest end-of-day queries. expiration rolls by expiration timing and uses daysToExpiration when it is supplied. combined rolls using a combination of volume and open interest and ignores daysToExpiration. When the main plot changes to a futures shortcut symbol such as a root-based contract, the chart sets contractRoll to expiration; for concrete futures contracts it sets combined.

Behavior

Aggregation supports two sub-actions:

  • Get: returns the current aggregation object in the same shape as aggregation Update fields.
  • Update: merges provided aggregation fields into the current aggregation.

Only provided fields are changed.

TopOfBook is a specialized tick aggregation which fetches historical quote rows (best bid, best ask and their sizes) instead of the usual trade-based tick shape. It is primarily meant for consumers which read the raw container data directly, such as historical tables, and is not intended for normal chart visualization.

Example (Get):

const currentAggregation = chart.change({
    id: "Aggregation",
    context: { id: "Get" },
});

Example (Update to 5-minute bars):

chart.change({
    id: "Aggregation",
    context: {
        unit: "Intraday",
        size: 5,
        spec: "None",
    },
});

Example (Update to nearest daily futures):

chart.change({
    id: "Aggregation",
    context: {
        unit: "Day",
        size: 1,
        spec: "Nearest",
        daysToExpiration: 1,
        contractRoll: "expiration",
    },
});