Getting started

Data Structure and Binding

Data Structure

AG Charts expects data as an array of objects, where each object represents a data point.

{
    data: [\
        { year: '2021', sales: 50000, profit: 15000 },\
        { year: '2022', sales: 65000, profit: 22000 },\
        { year: '2023', sales: 78000, profit: 28000 },\
    ],
}

• The data can be any array of objects, with properties being mapped to chart elements like axes, size, and colour.
• TypeScript Generics support enables compile-time checks and auto-complete for the elements of the data[] property.
• Hierarchical Series such as Treemap and Sunburst use a children array to represent nested levels.

Binding Data To Series

Every series in a chart has _Key properties for connecting the visualisation elements to the data fields.

These properties include xKey and yKey for cartesian charts, colorKey for heatmap and angleKey for pie series.

Angular Example - Data Configuration - Basic Data

{
    data: [\
        { year: '2021', women: 25, men: 20 },\
        { year: '2022', women: 28, men: 22 },\
        { year: '2023', women: 32, men: 24 },\
    ],
    series: [\
        {\
            type: 'bar',\
            xKey: 'year',\
            yKey: 'women',\
            yName: 'Women',\
        },\
        {\
            type: 'bar',\
            xKey: 'year',\
            yKey: 'men',\
            yName: 'Men',\
        },\
    ],
}

In this example:

• The data array contains the data for all series in the chart.
• Series 1 visualises the women field on the y-axis using yKey: 'women'.
• Series 2 visualises the men field on the y-axis using yKey: 'men'.
• The xKey: 'year' is used by both series, determining the x-axis categories.

The _Key properties vary by series type - see the Series Options for more details.

Per-Series Data

All series use the root-level data option by default, and this approach is recommended for best performance. However, to support scenarios where different data sources are needed, each individual series can declare its own data option.

{
    series: [\
        {\
            type: 'bar',\
            data: [\
                { year: '2021', women: 25 },\
                { year: '2022', women: 28 },\
                { year: '2023', women: 32 },\
            ],\
            xKey: 'year',\
            yKey: 'women',\
            yName: 'Women',\
        },\
        {\
            type: 'bar',\
            data: [\
                { year: '2021', men: 20 },\
                { year: '2022', men: 22 },\
                { year: '2023', men: 24 },\
            ],\
            xKey: 'year',\
            yKey: 'men',\
            yName: 'Men',\
        },\
    ],
}

When a series specifies its own data array, it overrides the root-level data option for that series only. Other series continue to use root-level data.

Field Dot Notation

By default, AG Charts supports dot notation for accessing nested properties in your data.

{
    data: [\
        { user: { name: 'Alice', age: 30 } },\
        { user: { name: 'Bob', age: 25 } },\
    ],
    series: [\
        {\
            type: 'bar',\
            xKey: 'user.name', // Accesses nested property\
            yKey: 'user.age',\
        },\
    ],
}

Updating Data

After chart creation, data can be updated by mutating the data object.

For details on update methods, see the Create/Update API Reference.

High Frequency Updates

For high-frequency or streaming data, use applyTransaction() to update specific items without replacing the entire dataset. This is significantly faster for small changes to large datasets.

chart.applyTransaction({
    add: [{ date: new Date(), value: 42 }],
    remove: [oldDataPoint],
    update: [{ ...updatedDataPoint }],
});

Set dataIdKey on the chart options to identify items by a unique field instead of by object reference. See Transactions for details.

For details on transaction operations, see High-Frequency Data.