---
url: https://chartbuddy.io/embed/docs/concepts/data-model.md
---
# Data model

Every Insight is driven by a **`chartData`** document: a chart type, a 2D `seriesData` grid, and optional furniture / axes / annotations.

Deep field reference, validation codes, waterfall rules, and merge behaviour: **[chartData schema](/api/chart-data)**.

## Required

| Field | Type | Notes |
|---|---|---|
| `chartType` | `string` | Chart type id – see [chart types](/chart-types/) |
| `seriesData` | 2D array | Layout depends on type |

## Recommended shell

```js
{
  chartType: 'clusteredBar',
  isDataTransposed: true,
  seriesData: [/* … */],
  title: { visible: true, text: '…' },
  subtitle: { visible: false, text: '' },
  legend: { visible: true },
  orientation: 'vertical', // or 'horizontal'
}
```

## chartType values

`clusteredBar` · `stackedBar` · `stackedBar100` · `line` · `stackedArea` · `stackedArea100` · `pie` · `scatter` · `waterfall` · `mekko` · `barMekko` · `combo`

You can also pass `donut` (pie with a hole) or `bubble` (scatter with a larger marker). `getChartData()` returns `pie` / `scatter` with those defaults applied. Details: [chartData schema – donut & bubble](/api/chart-data#donut--bubble).

## seriesData layouts (quick)

**Bar / line / area / stacked / waterfall / mekko / combo** – rows = series (`isDataTransposed: true`):

```js
[
  ['', 'Q1', 'Q2', 'Q3'],
  ['Revenue', 100, 112, 125],
  ['Costs', 60, 66, 70],
]
```

**Pie** – category / value:

```js
[
  ['Category', 'Value'],
  ['North', 45],
  ['South', 30],
]
```

**Bar Mekko** – row 1 = widths (not drawn); later rows = stacked heights:

```js
[
  ['', 'Enterprise', 'Mid-market', 'SMB'],
  ['Accounts', 120, 85, 200],
  ['Core revenue', 48, 16, 8],
  ['Add-ons', 14, 12, 10],
]
```

**Scatter** – no transpose; columns are metrics:

```js
[
  ['', 'Metric X', 'Metric Y', 'Size', 'Group'],
  ['Point 1', 10, 15, 8, 'A'],
]
```

Full layout rules, minima, and ragged-grid behaviour: [chartData schema – seriesData](/api/chart-data#seriesdata-layouts).

## Next

* [chartData schema](/api/chart-data) – top-level map, option bags, patches, validation
* [Defaults & merging](/concepts/defaults)
* [Axes](/axes/) · [Configuration](/configuration/) · [Chart types](/chart-types/)