Chart Types

The eight chart types, the data each expects, and the options available per chart.

visualize supports eight chart types. Omit chartType to auto-detect from the shape of the result, or pass it to force a specific one. Columns are mapped to roles (dimension, measure, time) automatically; use encode to map them explicitly when names aren't obvious.

Common options

Passed as visualize arguments and shared across most chart types:

Option	Type	What it does
`chartType`	enum	One of the types below. Omit to auto-detect.
`title`	string	Chart title.
`encode`	object	Map columns to roles — see Encoding.
`reference`	`{ target?, average? }`	Horizontal reference line(s) on the value axis: a fixed `target` and/or the series `average`.
`stacking`	`stacked` / `grouped` / `stacked100`	Bar and area only — see Bar.
`horizontal`	boolean	Bar only — render horizontal bars.

Formatting (currency, percent, plain number, and time granularity) is inferred from column types and names, or declared via typed fields on the runSql result. Axis labels, the legend, sorting, and time-gap filling are handled for you.

Encoding

encode maps columns when auto-detection needs a hint:

Field	Applies to	Meaning
`x`	all	The category / time / x-measure column.
`y`	all	Measure(s) to plot — a single name, or an array for multiple series.
`series`	bar, line, area	A categorical column to pivot into one series per value (long table → wide).
`y2`	bar, line, area	Measure(s) on a secondary right axis, drawn as a line (e.g. a % over $ bars).
`line`	bar	Measure(s) drawn as a line instead of bars on the same axis (combo, e.g. actual vs target).
`size`	scatter	A third numeric column mapped to point size (turns scatter into a bubble chart).

Bar

Categories on one axis, one or more measures on the other.

Data: a dimension (x) + one or more measures (y).
Multiple series: pass y: ["revenue", "cost"], or pivot a long table with series (e.g. x: month, series: region, y: revenue).
Stacking: stacked (absolute), stacked100 (normalised to 100%), or grouped (side by side).
Horizontal: horizontal: true — auto-applied when there are many categories.
Combo: encode.line renders chosen measures as a line on the same axis (actual vs target); encode.y2 puts measures on a secondary right axis as a line (e.g. a percentage over dollar bars).
Reference lines: reference: { target: 100000, average: true }.

Line

A measure over an ordered or time axis.

Data: a time or ordered x + one or more measures (y); use series to pivot a long table.
Numeric x: a numeric x-axis renders on a linear scale rather than as categories.
Time handling: points are sorted by x and missing time intervals are filled so breaks render correctly.
Secondary axis: encode.y2 plots a second metric on the right axis.
Reference lines are supported.

Area

Same as line, emphasising magnitude.

Stacking: stacked or stacked100 to show composition over time.

Pie

Parts of a whole.

Data: one dimension (slices) + one measure (values).
Best for a handful of categories — use a bar chart when there are many.

Scatter

Relationship between two measures.

Data: two measures, x and y (a point cloud — no aggregation or pivoting).
Bubble: add encode.size (a third measure) to scale each point.
Labels: a dimension column, if present, identifies each point in the tooltip.

Funnel

Stages of a sequential process.

Data: a dimension (stages, in order) + a measure (the value at each stage).

Waterfall

Running total of additive contributions.

Data: ordered steps (a dimension) + a signed measure (the deltas).
The first and last steps render as full bars anchored at zero (totals); the steps between float as deltas.

Table

Raw rows when a chart wouldn't add clarity.

Data: any columns, each rendered with its inferred format (currency, percent, date).
The fallback when the result is a single metric or an unrecognised shape.

How the type is auto-detected

When chartType is omitted:

a time column → line
a categorical dimension → bar
all-numeric columns → bar (the lowest-cardinality column becomes the x-axis)
a single metric or unknown shape → table

pie, scatter, funnel, and waterfall are never auto-selected — request them with chartType.

On this page