Chart Types

All eight chart types (line, bar, area, pie, scatter, funnel, waterfall, table), the data shape each expects, and how auto-detection picks one.

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.

Render caps

A result too wide or too dense to read is reduced before it renders. Each reduction adds a note to the returned spec, so both the agent and the reader see that it happened. The caps are listed per chart type below. Across bar, line, and area, a series pivot keeps at most 12 series: the largest 11 by total, with the rest summed into one Other series.

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. Bars stay vertical by default; the widget only auto-flips to horizontal when a category label is longer than 12 characters, since a long label doesn't fit under a vertical bar.
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 }.
Render cap: past 30 categories, only the top 30 by value are kept and the tail is dropped. There is no Other bar, which would misread when the tail is large.

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.
Render cap: past 2,000 points the series is stride-downsampled, keeping every Nth point plus the last, so the range and shape survive.

Area

Same as line, emphasising magnitude.

Stacking: stacked or stacked100 to show composition over time.
Render cap: the same 2,000-point downsample as line.

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.
Render cap: at most 8 slices. A slice ranked 8th or lower, or worth under 2% of the total, folds into one Other slice. A lone small slice is left as itself. Non-positive values are dropped first, unless every value is negative, in which case magnitudes are plotted.

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.
Render cap: past 2,000 points the cloud is stride-sampled down. When points are grouped by a dimension, at most 12 groups are coloured: the largest 11 by point count, with the rest as Other.

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