Charts
A chart wraps a connector's named query into a visualisation. Defined in Settings → Charts, picked by type — line, bar, column, area, pie, donut, scatter — and reused as a panel in any number of dashboards.
This page covers the Charts builder, every field on the editor and the type-specific options each chart type unlocks.
At a glance
Editing a chart
In Settings → Charts → ➕ New chart, the editor opens with the Type picker at the top. Picking a type expands the form to the fields that type needs.
Common fields
| Field | Effect |
|---|---|
| Type | The chart type — see Types below. Changing the type adapts the rest of the form. |
| Title / Subtitle | Shown above the chart. Subtitle is optional. |
| Connector / Query | The data source. Dropdowns of the connectors and their named read queries. |
| Parameters | Table of fixed values for the query parameters — same shape as elsewhere. Supports the ${week.monday} / ${month.last} tokens documented in Parameter binding. |
| Height | CSS height of the rendered chart. Default 320px. |
| Legend | Toggle + position (bottom / right / top). Default on, bottom. |
| Tooltip | Toggle. Default on. |
| Grid | Toggle. Default on. |
| Refresh interval | Seconds between auto-refresh ticks. 0 (default) = manual only. |
X axis
| Field | Effect |
|---|---|
| Field | Dropdown of the columns the query returns. |
| Label | Shown under the chart. |
| Format | Date / number format applied to tick labels. Dates use date-fns syntax (yyyy-MM, dd/MM); numbers use Intl.NumberFormat notation. |
| Tick interval | preserveStartEnd (default) / auto / an integer "keep one tick out of N". |
Series
Series are a sortable list. Each row exposes:
| Field | Effect |
|---|---|
| Field | Column returned by the query. |
| Label | Legend / tooltip label. |
| Colour | Hex / CSS colour. The framework picks a palette when empty. |
| Format | Number format applied to tooltip and dot labels. |
| Axis | left (default) / right. Use right for two-scale charts (e.g. count + amount). |
| Dot (line / area only) | Toggle. Hide dots for a cleaner sparkline. |
Types
| Type | Shape | Typical query |
|---|---|---|
| Line | One line per series, X axis horizontal. | Time series — x = date, series = numeric. |
| Area | Same as line, area below filled. Stacked toggle available. | Cumulative or composition over time. |
| Bar | Vertical bars per X tick. Stacked / Horizontal toggles available. | Counts per period, top-N rankings. |
| Column | Alias of bar — exists for the convention "column = vertical, bar = horizontal". | |
| Pie / Donut | One slice per row; X-field labels each slice, series sizes them. | Share of a total over a small category set. |
| Scatter | Two numeric axes; one dot per row. Optional Size field makes a bubble chart. | Correlation between two measures. |
Each type-specific toggle / field appears in the editor only when the type is selected.
Type-specific options
| Type | Extra fields |
|---|---|
| Line / Area | Smooth (monotone-cubic interpolation), Stacked (area only), Null handling (Connect / Gap). |
| Bar / Column | Stacked, Bar size, Horizontal. |
| Pie / Donut | Inner radius (donut only), Outer radius, Label position (outside / inside / none), Palette. |
| Scatter | Size field, Size range ([min_px, max_px]). |
Group by
The Group by field (in the editor's Series section) turns one source column into N parallel series without listing each series by hand. Useful when the set of values isn't known ahead of time — invoice statuses, sales reps, …
| Field | Effect |
|---|---|
| Group-by field | Column whose distinct values become the series. |
| Y field | Column the framework sums / takes the first value of per group. |
| Palette | Array of colours used for the generated series, in order of first appearance. Falls back to the default palette when empty. |
When Group by is set, the per-series list above collapses to a single Y field and a colour palette — the framework pivots the rows itself.
Preview
The Preview button (top of the editor) renders the chart inline with the current settings. The preview hits the live database (or whatever pool the connector points at) and shows the latest data — useful to confirm a colour change before saving.
Reusing a chart
A saved chart is referenced by its id from any dashboard. Define once, reference everywhere — change the data source on the chart and every dashboard panel reflects it.
In the dashboard builder, adding a chart panel is a Chart dropdown of every chart on the install + a Position drag-and-drop on the grid.
Permissions
A chart inherits the permission of its underlying query — a caller who can't run sql:billing:monthly-invoice-counts doesn't see the chart in a dashboard. The framework prunes the panel silently rather than rendering a 403 placeholder, so dashboards stay informative.
Under the hood
Chart definitions live in charts.toml. Operators do not edit this file by hand; the Charts builder is the canonical interface. Advanced operators can reach for the Raw TOML tab as an escape hatch.
What's next
- Dashboards — how a chart lands on a dashboard panel.
- Parameter binding — fixed values, tokens, cascades.
- Concepts → Connectors — the connector that backs the chart's data.