---
title: "Data"
description: "A chart stores its numbers in the document, as Chart Data."
canonical_url: "https://tiptap.dev/docs/diagrams/data/overview"
---

# Data

A chart stores its numbers in the document, as Chart Data.

- **A column** has an `id`, a `label` and a `role`: `'label'` for the column that names the
  rows, `'series'` for a column of values.
- **A row** is a list of cells, one per column.

## Where the data comes from

| Way in              | What happens                                                                                                 | Page                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| Typed rows          | `:::` in an empty paragraph opens the Quick Input; rows such as `Jan \| 2` become a chart, Mermaid a diagram | [Quick Input](https://tiptap.dev/docs/diagrams/data/quick-input.md)    |
| A table             | A table becomes a chart, or a chart follows a table as it is edited                                          | [Tables](https://tiptap.dev/docs/diagrams/data/tables.md)              |
| A file or a service | A chart keeps a snapshot of a CSV or JSON URL, or of a provider you write, and synchronizes on request       | [Data Sources](https://tiptap.dev/docs/diagrams/data/sources.md)       |
| Pasted text         | A Mermaid chart such as `pie` or `sankey-beta`, rows from a spreadsheet, or rows in a known format           | [Pasting](https://tiptap.dev/docs/diagrams/data/pasting.md)            |
| Code                | `insertChart` with Chart Data, or `insertChartFrom` with text in a registered format                         | [Charts](https://tiptap.dev/docs/diagrams/charts/overview.md#commands) |
| A model             | Tool calls that write through the same Commands                                                              | [Tools for a model](https://tiptap.dev/docs/diagrams/guides/ai.md)     |

## Which columns are drawn

- Which columns a chart draws is set in the Chart Spec, the chart's settings, under `encoding`.
- The data keeps every column.
- A synchronization replaces all columns without losing the choice.

## Commands

### updateChartData

Replaces the Chart Data.

```ts
editor.commands.updateChartData({ data })
```

| Option | Type        | Description                                          |
| ------ | ----------- | ---------------------------------------------------- |
| `data` | `ChartData` | The new Chart Data                                   |
| `pos`  | `number`    | The chart's position. Defaults to the selected chart |

Returns `false` when the chart's linked source is read-only.

### setChartLabelColumn

Makes one column name the rows and draws every other column the chart type can draw.

```ts
editor.commands.setChartLabelColumn({ label: 'region' })
```

| Option  | Type     | Description                                          |
| ------- | -------- | ---------------------------------------------------- |
| `label` | `string` | The id of the column that names the rows             |
| `pos`   | `number` | The chart's position. Defaults to the selected chart |

- `encoding.series` becomes every other column the chart type can draw: the number columns,
  or every column for a type with the `matrix` shape.
- Choosing the first column removes `encoding`.
- `encoding.seriesIn` is kept.
- `encodingForLabel(data, label, shape)` from `@tiptap-pro/extension-diagrams/core` returns the
  same encoding without writing it.

Returns `false` for a column the data does not have.

### setChartSeriesIn

Decides whether a column or a row is a series.

```ts
editor.commands.setChartSeriesIn({ seriesIn: 'rows' })
```

| Option     | Type                  | Description                                          |
| ---------- | --------------------- | ---------------------------------------------------- |
| `seriesIn` | `'columns' \| 'rows'` | `'columns'` is the default. `'rows'` swaps the two   |
| `pos`      | `number`              | The chart's position. Defaults to the selected chart |

- **With `'rows'`** each row becomes a series named by its label, and each drawn column
  becomes a category.
- **For example**, `Month | Visitors` with three months draws, with `'rows'`, one category,
  Visitors, with a bar each for Jan, Feb and Mar.
- **Only `spec.encoding.seriesIn` changes.** `label` and `series` are kept.
- **After the swap** `spec.series` styles and `spec.palette` are keyed by the row labels,
  since they apply to the series as drawn.
- `encodeChartData(data, encoding)` returns the Chart Data a Renderer draws.

### updateChartFrom

Replaces data and spec from content in a registered format.

Read one chart in the chart syntax, as Chart JSON or as Mermaid, change the text and write it back:

> **Interactive demo:** [DiagramsFormats](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsFormats)

```ts
editor.commands.updateChartFrom({ format: 'chart-syntax', content: 'Jan | 2\nFeb | 3' })
```

| Option    | Type     | Description                                          |
| --------- | -------- | ---------------------------------------------------- |
| `format`  | `string` | The id of a registered format                        |
| `content` | `string` | The content in that format                           |
| `pos`     | `number` | The chart's position. Defaults to the selected chart |

Returns `false` when the content cannot be read or the chart is read-only.

### updateChartFromGrid

Replaces the data from a grid of strings.

```ts
editor.commands.updateChartFromGrid({ grid })
```

| Option | Type         | Description                                          |
| ------ | ------------ | ---------------------------------------------------- |
| `grid` | `string[][]` | Row 0 is the header, column 0 the labels             |
| `pos`  | `number`     | The chart's position. Defaults to the selected chart |

- Pairs with `readGrid` for a form of input fields.
- Pasted spreadsheet rows go through this Command; see
  [Onto a selected chart](https://tiptap.dev/docs/diagrams/data/pasting.md#onto-a-selected-chart).

### updateChartFromTable

Replaces the data from table JSON.

```ts
editor.commands.updateChartFromTable({ table })
```

| Option  | Type       | Description                                          |
| ------- | ---------- | ---------------------------------------------------- |
| `table` | `JSONNode` | A table Node as JSON                                 |
| `pos`   | `number`   | The chart's position. Defaults to the selected chart |

Pairs with `readTable`.