--- title: "Data" description: "A chart stores its values in the document as Chart Data, a list of columns and a list of rows." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/data/overview" --- # Data A chart stores its values in the document as Chart Data, a list of columns and a list of rows. 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 | Rows such as `Jan \| 2`, typed after `:::`, become a chart | [Quick Input](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md) | | A table | A table becomes a chart, or a chart follows a table while you edit the table | [Tables](https://tiptap-docs.lin52025i.qzz.io/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 | [Data Sources](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md) | | Pasted text | A Mermaid chart becomes a chart, rows become a selected chart's new data | [Pasting](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/pasting.md) | | Code | `insertChart` with Chart Data, or `insertChartFrom` with text in a format | [Charts](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#commands) | | An AI model | Tool calls that write through the same commands | [Tools for a model](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai.md) | ## Which columns are drawn The Chart Data keeps every column. The `encoding` field of the Chart Spec, the chart's settings, holds the ids of the columns the chart draws, in the editor and in every export: | Field | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `label` | The column that names the rows | | `series` | The columns drawn, in that order | | `seriesIn` | `'rows'` swaps rows and columns, see [`setChartSeriesIn`](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/overview.md#setchartseriesin) | - Without `label`, the column with the role `'label'` names the rows. - Without `series`, every other column with the role `'series'` is drawn. - An id that is not in the data is ignored, so a chart still draws after a source renames a column. - When no id in `series` is in the data, every series is drawn. - A synchronization replaces all columns and keeps `encoding`, see [Data Sources](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md#showing-only-some-columns). Set `encoding` with [`updateChartSpec`](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#updatechartspec), or with the commands below. ## 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 there is no chart at `pos` or selected, or when the chart's linked source is read-only and the new data differs from the current data. ### setChartLabelColumn Makes one column name the rows. `encoding.series` becomes 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 | For most types, the drawn columns are those with the role `'series'`. For a type that reads its rows with the `matrix` shape, such as the `matrix` chart type, it is every column, see [Register your own chart type](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-chart-types.md#fields-of-a-chart-type). Choosing the first column removes `label` and `series` from `encoding`. `encoding.seriesIn` is always kept. Returns `false` for a column the data does not have. ### setChartSeriesIn Decides whether each column or each row of the data is a series. A series is one set of values the chart draws, such as one line or one color of bars. ```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. Take a bar chart of this data: ```txt Month | Visitors Jan | 120 Feb | 150 Mar | 170 ``` | `seriesIn` | Categories | Bars in each category | | ----------- | ------------- | ------------------------- | | `'columns'` | Jan, Feb, Mar | One bar, Visitors | | `'rows'` | Visitors | Three bars, Jan, Feb, Mar | Only `spec.encoding.seriesIn` changes. `label` and `series` are kept. After the swap, `spec.series` styles are keyed by the row labels, and `spec.palette` colors the series in the order they are drawn. ### updateChartFrom Replaces the data and the spec from content in a registered format. Read a chart as Chart syntax, Chart JSON or 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 | Use it with [`readGrid`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/storage.md#reading-a-charts-data) to edit the data in a form of input fields. Spreadsheet rows [pasted onto a selected chart](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/pasting.md#onto-a-selected-chart) go through it. Returns `false` in the same cases as `updateChartData`. ### 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 | Use it with [`readTable`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/storage.md#reading-a-charts-data), which returns a chart's data as table JSON. Returns `false` in the same cases as `updateChartData`. ## Helpers for tooling From `@tiptap-pro/extension-diagrams/core`: | Function | Returns | | -------------------------------------- | ---------------------------------------------------------- | | `encodeChartData(data, encoding)` | The Chart Data a Renderer draws | | `encodingForLabel(data, label, shape)` | The encoding `setChartLabelColumn` writes, without writing |