Chart

What It Is

The Chart is a canvas item that turns a set of result rows into a visual chart — bar, line, area, pie, doughnut, radar, or polar area. You drop it onto a canvas, point it at data (a stored Query or SmartSQL), tell it which column is the label and which columns are the values, and it draws the chart for the viewer.

It belongs to the Charts group in the canvas item gallery. Like every other item it lives inside the draft-based builder workflow described in Canvas Items And CanvasBuilder.

Why It Matters

Tables (Views) answer "what are the records?". Charts answer "what is the shape of the data?" — trends over time, distribution across categories, share of a whole. A reporting canvas usually wants both: a few charts at the top for the overview, tables below for the detail.

The Chart item is deliberately split into two layers so it stays approachable but never becomes a dead end:

Clickable controls for the common 90% — chart type, colours, legend, axis labels, stacking.
An advanced JSON escape hatch for anything the underlying library supports that the controls don't expose.

Mental Model

Think of the Chart in three stages:

Source → rows. A Query or a SmartSQL statement produces a flat result set: rows of named columns.
Rows → series. You pick one column as the label (the category / x-axis) and one or more columns as the values (the series / y-axis). Each value column becomes one dataset.
Series → picture. The chosen chart type and presentation options decide how those datasets are drawn.

The most important consequence: charts want aggregated data. A chart of "tasks per status" is a GROUP BY status query returning one row per status — not the raw task list. Shape the data in the source; the Chart only visualises what it receives.

The data shaping happens entirely on the server. The browser receives only the finished, computed chart definition — never your SQL.

How To Configure

1. Choose a data source

Option	What it does	When to use
Stored Query	Pick a saved Query from the dropdown.	The aggregation already exists as a reusable Query, or non-developers maintain it.
SmartSQL	Write SQL directly into the item, using `{Type.property}` placeholders that resolve to real tables and columns.	One-off chart logic that doesn't deserve its own Query, or quick prototyping.

SmartSQL uses the same placeholder syntax as custom Queries, so you stay in domain terms instead of raw table names:

SELECT {Task.status!} AS status, COUNT(*) AS total
FROM {Task}
GROUP BY {Task.status!}

2. Map columns to the chart

Once the source can be inspected, the Label column and Value columns inputs become dropdowns auto-populated with the detected columns. Pick the category column for the label, and one or more numeric columns for the series.

If the columns can't be detected statically (for example, SQL assembled dynamically at render time), the inputs fall back to free text — type the column name, or a comma-separated list of names, exactly as they appear in the result set.

Pie / doughnut / polar area use only the first value column — one slice per row, coloured from the palette.
Bar / line / area / radar draw one dataset per value column, so you can compare several measures side by side.

3. Presentation (clickable)

Option	Controls
Chart type	Bar, line, area, pie, doughnut, radar, polar area.
Colour palette	A named scheme (Default, Pastel, Vivid, Cool, Warm, Monochrome).
Custom colours	An explicit colour list that overrides the palette.
Show legend / Legend position	Whether and where the legend appears.
Chart title	An optional heading drawn above the chart.
Height (px)	The drawing height; the chart fills the canvas width responsively.

4. Cartesian-only options

These appear only for bar, line, and area charts:

Option	Controls
Stacked	Stack datasets instead of grouping them.
Y axis begins at zero	Anchor the value axis at zero (recommended for honest bar charts).
X axis label / Y axis label	Axis captions.
Horizontal bars	(Bar only) Lay bars horizontally.
Smooth lines	(Line / area only) Curve the line instead of straight segments.

5. Advanced JSON escape hatch

Two optional fields let you reach anything the controls don't cover:

Chart.js options (advanced) — an options object that is deep-merged over everything computed from the controls. Use it to fine-tune tooltips, ticks, animations, or any Chart.js option.
Per-dataset overrides (advanced) — applied to every generated dataset (border width, point style, fill behaviour, …).

Because these merge on top of the computed configuration, you only specify what you want to change. For example, hiding the legend purely from the escape hatch:

{ plugins: { legend: { display: false } } }

Example

Goal: a canvas widget showing open tasks per assignee.

Add a Chart item to the canvas.

Data source → SmartSQL:

SELECT {User.full_name!} AS assignee, COUNT(*) AS open_tasks
FROM {Task}
JOIN {User} ON {Task.assigned_to} = {User.id}
WHERE {Task.status!} = 'open'
GROUP BY assignee

Label column → assignee, Value columns → open_tasks.
Chart type → Bar, Horizontal bars → on, Y axis begins at zero → on.
Preview the canvas — each assignee becomes a horizontal bar sized to their open task count.

Best Practices

Aggregate in the source. One row per category, with a numeric measure column. Don't feed raw record lists to a chart.
Pick the type for the question. Trend over time → line; share of a whole → pie/doughnut; comparison across categories → bar; multi-axis profile → radar.
Keep categories few. Pie and doughnut charts become unreadable past ~7 slices; prefer a bar chart for long category lists.
Reach for the escape hatch last. If a setting exists as a clickable control, use it — the JSON field is for the genuinely uncovered cases.

Queries — building the stored queries and SmartSQL the chart reads from.
Views — the tabular counterpart for record-level detail.
Canvases and Canvas Items And CanvasBuilder — where charts live and how the builder works.