Angular ChartsData Configuration and Update

This page describes how to provide data to be visualised by AG Charts, and how to update it.

Data Structure and Binding Copy Link

Data Structure Copy Link

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 color.
• 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 Copy Link

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.

{
    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 visualizes the women field using yKey: 'women'.
• Series 2 visualizes the men field using yKey: 'men'.
• The xKey: 'year' is used by both series, determining the category labels.

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

Per-Series Data Copy Link

By default, all series use the root-level data option, but each series can declare its own data. This is useful when different series have different data sources.

{
    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 Copy Link

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

Use the suppressFieldDotNotation option to disable this feature if your field names contain the . character.

{
    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 Copy Link

After chart creation, you can update the data by mutating the data object.

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

High Frequency Updates Copy Link

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 }],
});

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

Asynchronous Data Copy Link

The dataSource callback allows fetching data asynchronously as the user zooms and pans.

{
    dataSource: {
        getData: ({ windowStart, windowEnd }) => {
            return FakeServer.get(windowStart, windowEnd);
        },
    },
}

See Asynchronous Loading for more details.