Skip to main content
The chart component plots data from your SQL queries as interactive visualizations. Supports line, area, bar, column, pie, scatter, bubble, heatmap, rangeBar, and treemap charts.

Basic Usage

SELECT 'chart' AS component,
       'Sales Over Time' AS title,
       'line' AS type;
       
SELECT 2021 AS x, 150 AS y;
SELECT 2022 AS x, 230 AS y;
SELECT 2023 AS x, 320 AS y;

Top-Level Properties

title
text
The name of the chart
type
text
required
Type of chart: “line”, “area”, “bar”, “column”, “pie”, “scatter”, “bubble”, “heatmap”, “rangeBar”, “treemap”
time
boolean
Whether the x-axis represents time. Values are parsed and formatted as dates.
ymin
number
Minimum value for the y-axis
ymax
number
Maximum value for the y-axis
xmin
number
Minimum value for the x-axis
xmax
number
Maximum value for the x-axis
xtitle
text
Title of the x-axis, displayed below it
ytitle
text
Title of the y-axis, displayed to its left
ztitle
text
Title of the z-axis, displayed in tooltips (for 3D/bubble charts)
xticks
integer
Number of ticks on the x-axis
yticks
integer
Number of ticks on the y-axis
ystep
number
Step between ticks on the y-axis
marker
number
Size of data point markers
labels
boolean
Whether to show data labels on the chart
color
color
Color for the chart. Can be repeated for multiple series.
stacked
boolean
Whether to stack values from different series
toolbar
boolean
Display a toolbar for downloading data as CSV or image
logarithmic
boolean
Display the y-axis in logarithmic scale
horizontal
boolean
Display bar chart with horizontal bars instead of vertical
height
integer
Height of the chart in pixels (default: 250)

Data Point Properties

x
number
required
Value on the horizontal axis
y
number
required
Value on the vertical axis
z
number
Value for the z-axis (used in bubble charts for size)
label
text
Alias for the “x” property
value
text
Alias for the “y” property (or array for rangeBar: [start, end])
series
text
Name of the series this point belongs to (for multi-series charts)

Examples

Line Chart with Time Series

SELECT 'chart' AS component,
       'Quarterly Revenue' AS title,
       'area' AS type,
       'blue-lt' AS color,
       5 AS marker,
       true AS time;

SELECT '2022-01-01T00:00:00Z' AS x, 15 AS y;
SELECT '2022-04-01T00:00:00Z' AS x, 46 AS y;
SELECT '2022-07-01T00:00:00Z' AS x, 23 AS y;
SELECT '2022-10-01T00:00:00Z' AS x, 70 AS y;
SELECT '2023-01-01T00:00:00Z' AS x, 35 AS y;
SELECT '2023-04-01T00:00:00Z' AS x, 106 AS y;

Pie Chart

SELECT 'chart' AS component,
       'Survey Answers' AS title,
       'pie' AS type,
       true AS labels;
       
SELECT 'Yes' AS label, 65 AS value;
SELECT 'No' AS label, 35 AS value;

Bar Chart

SELECT 'chart' AS component,
       'Quarterly Results' AS title,
       'bar' AS type,
       true AS horizontal,
       true AS labels;
       
SELECT 'Tom' AS label, 35 AS value;
SELECT 'Olive' AS label, 15 AS value;

Multi-Series Line Chart

SELECT 'chart' AS component,
       'Revenue' AS title,
       0 AS ymin,
       true AS toolbar;

-- Chicago Store
SELECT 'Chicago Store' AS series, 2021 AS x, 35 AS value;
SELECT 'Chicago Store' AS series, 2022 AS x, 15 AS value;
SELECT 'Chicago Store' AS series, 2023 AS x, 45 AS value;

-- New York Store
SELECT 'New York Store' AS series, 2021 AS x, 30 AS value;
SELECT 'New York Store' AS series, 2022 AS x, 55 AS value;
SELECT 'New York Store' AS series, 2023 AS x, 19 AS value;

Stacked Bar Chart

SELECT 'chart' AS component,
       'Expenses' AS title,
       'bar' AS type,
       true AS stacked,
       true AS toolbar,
       10 AS ystep;

SELECT 'Marketing' AS series, 2021 AS x, 35 AS value;
SELECT 'Marketing' AS series, 2022 AS x, 15 AS value;
SELECT 'Human resources' AS series, 2021 AS x, 30 AS value;
SELECT 'Human resources' AS series, 2022 AS x, 55 AS value;

Scatter Plot

SELECT 'chart' AS component,
       'GDP vs Growth Rate' AS title,
       'scatter' AS type,
       'Growth Rate' AS xtitle,
       'GDP (Trillions USD)' AS ytitle,
       500 AS height,
       8 AS marker,
       0 AS xmin,
       10 AS xmax,
       0 AS ymin,
       25 AS ymax,
       5 AS yticks;

SELECT 'Brazil' AS series, 2.5 AS x, 2 AS y;
SELECT 'China' AS series, 6.5 AS x, 14 AS y;
SELECT 'United States' AS series, 2.3 AS x, 21 AS y;
SELECT 'France' AS series, 1.5 AS x, 3 AS y;

Heatmap

SELECT 'chart' AS component,
       'Survey Results' AS title,
       'heatmap' AS type,
       'Database system' AS ytitle,
       'Year' AS xtitle,
       'purple' AS color;

SELECT 'PostgreSQL' AS series, '2000' AS x, 48 AS y;
SELECT 'SQLite' AS series, '2000' AS x, 44 AS y;
SELECT 'MySQL' AS series, '2000' AS x, 78 AS y;
SELECT 'PostgreSQL' AS series, '2010' AS x, 65 AS y;
SELECT 'SQLite' AS series, '2010' AS x, 62 AS y;
SELECT 'MySQL' AS series, '2010' AS x, 83 AS y;

TreeMap Chart

SELECT 'chart' AS component,
       'Quarterly Results By Region (in k$)' AS title,
       'treemap' AS type,
       true AS labels;

SELECT 'North America' AS series, 'United States' AS label, 35 AS value;
SELECT 'North America' AS series, 'Canada' AS label, 15 AS value;
SELECT 'Europe' AS series, 'France' AS label, 30 AS value;
SELECT 'Europe' AS series, 'Germany' AS label, 55 AS value;
SELECT 'Asia' AS series, 'China' AS label, 20 AS value;
SELECT 'Asia' AS series, 'Japan' AS label, 10 AS value;

Range Bar (Timeline)

SELECT 'chart' AS component,
       'Project Timeline' AS title,
       'rangeBar' AS type,
       true AS time,
       'teal' AS color,
       true AS labels,
       '2021-12-28' AS xmin,
       '2022-01-04' AS xmax;

SELECT 
    'Phase 1' AS series,
    'Operations' AS label,
    json_array('2021-12-29', '2022-01-02') AS value;

SELECT 
    'Phase 2' AS series,
    'Operations' AS label,
    json_array('2022-01-03', '2022-01-04') AS value;

Notes

Charts use the ApexCharts library for rich, interactive visualizations that work on all devices.
Use the time property when your x-axis represents dates or timestamps for automatic formatting and intelligent tick placement.
Enable the toolbar to let users download chart data as CSV or save the chart as an image.
For heatmaps, ensure consistent series names across x-axis values for proper rendering.

Build docs developers (and LLMs) love