Verdalia
← Back to Guides

Chart a table#

A Chart widget plots the rows of one table. This guide covers the mapping every chart kind shares, which is what lets you bind a chart once and then try it as a line, a bar, or a pie without re-entering anything.

Prerequisites#

A table whose rows carry the values you want to plot: one column to split the data by, and at least one numeric column to measure. If the table holds readings at a finer grain than you intend to chart, a workflow should aggregate it to that grain before it is written.

The mapping#

A chart is a query and a mapping. The query decides which rows are read; the mapping decides what becomes of them. The mapping has exactly two parts, and they are the same two for all six kinds:

  • x is what splits the data — the column whose values become points along an axis, bars, or wedges.
  • y is what is measured — a numeric column, or several.

These are roles, not screen positions. A horizontal bar chart draws its measure across and its domain down the side; the measure is still y. That is why changing the kind keeps the bindings: nothing about x and y depends on where the drawing puts them.

Three things follow from the mapping having exactly this shape:

  1. A second measure makes a multi-series chart. Adding y columns is the whole mechanism — there is no separate mode to choose.
  2. Splitting one measure does the same job from long-form data. Where a wide table has one column per series, a long one has a column naming the series; Series grouping field reads that column. It applies to a single measure, because splitting several would need a third dimension the plot does not have.
  3. Round kinds take one measure and no split. A pie has one wedge per x value and nowhere to lay a second dimension.

The axis kind — time, numeric, category — is read from the column's declared kind, so a Date column plots as time without being told. Everything else has a default worth having: linear scale, plain numbers, ordered by x ascending.

Build one#

1. Add a Chart widget to a Pegboard. Open Edit widget from its context menu.

2. Choose the table under Table, at the top of the editor.

3. Bind the two columns under Plot fields. For a line chart, choose the numeric column in Values (vertical axis) and its time or category column in Horizontal axis field. The live Preview below the settings reads real rows.

4. Try the other kinds. Use the dropdown under Plot to switch between them. Compatible bindings survive the switch.

Note: a chart reads at most 1,000 rows. Use search, filters and the limit under Rows to choose the returned window. A limit outside 1–1,000 stays visible with an error instead of being changed to another number.

Which observations are retained#

A chart with a time-based horizontal axis keeps the latest observations by default. Under Rows, Truncate chooses which end of the history is discarded:

  • Oldest observations (keep latest) retains the newest N observations.
  • Newest observations (keep earliest) retains the oldest N observations.

The horizontal date/time column determines age, without a separate source sort. Offset counts from the retained end: with the default choice, offset 10 skips the ten newest observations. Ordering only controls how the retained points are drawn; changing its direction does not change which dates survive the limit. Non-time charts use their explicit source Order instead.

Beyond the two bindings#

The groups below the bindings start shut and print what they currently hold, so a chart with nothing unusual set stays short:

  • Appearance names a series and gives it one of the chart palettes, and chooses how numbers read — plain, compact, percent, currency, bytes, or a duration.
  • Scale and range switches to a logarithmic axis and pins a minimum or maximum. Line charts fit their automatic range to the displayed values; linear bars and areas retain a zero baseline. Set a minimum of 0 for a zero-based linear line chart. With more than one series this group also offers stacking.
  • Ordering sorts by x, by y, or by whatever order the query returned. Ordering by y on a pie is what "largest wedge first" means.

Candles and session gaps#

Choose Candles, then bind Open, High, Low and Close to numeric columns. Volume is available for tooltips. A time column on the horizontal axis preserves elapsed time by default.

Ignore session gaps spaces the observed candles evenly. Dashed purple lines mark intervals longer than 1.5 times the typical observed spacing, between the candles on either side of a gap. This is inferred from the observations, not an exchange calendar; fewer than three candles cannot establish a typical interval. Timestamps and prices in tooltips remain unchanged.

One chart per group#

A Chart group partitions a table by a column and draws each group in its own chart. Use it for one price chart per ticker, or one sales chart per product. Series grouping field still works inside scalar charts: grouping by product and splitting by region gives each product its own chart containing the regions.

1. Add a Chart group widget and choose its table. The table comes before any column selectors.

2. Choose Group by under Grouping. Text, select, integer, decimal, boolean, date and date-and-time columns can group rows, and so can the row id. Empty text, the text null, and an unspecified value remain three distinct groups.

3. Set Sort groups by and Direction. Group key orders the keys themselves. Another column uses the smallest non-null value across all matching rows in each group; descending reverses those same minima. Ties use the group key ascending, and nulls stay last.

4. Set First N groups if you want a total cap. Leave it blank to make all matching groups reachable with Load more groups. Groups load in pages rather than all at once.

5. Configure the plot below Grouping, using the same columns and appearance controls as an ordinary Chart.

6. Choose the row window under Rows. Time-based charts use Truncate independently within each group; other charts use Row order. Rows per group caps each chart at 1–1,000 rows, and Skip rows per group moves that window from the selected end. Search and filters apply before grouping. The separate Ordering settings only arrange points already returned, so changing plot order cannot recover a row outside the window.

Automatic scales fit each chart independently. An explicit minimum or maximum applies to every chart. A header such as 2 of 600 rows means the chart shows a window, not the group's complete history. Skipping beyond the available rows leaves a named empty chart; one group's malformed candles do not hide its neighbours.

When a chart will not draw#

A chart says why rather than drawing an empty frame. The three it reports are worth knowing in advance:

Rows missing a value for x or y are skipped, so one gap does not take the chart down. If every row is missing one, the chart says so and names the columns — check that the table declares them and that the workflow writing the rows fills them.

Two rows sharing an x value cannot both be plotted in one series. Aggregate to the grain you are charting, or split by the column that distinguishes them.

A logarithmic axis cannot plot negative values. Zero values are drawn just above zero and still read as 0 in tooltips. Explicit logarithmic bounds must be positive. A wedge cannot be sized by a negative number.

Next steps#

Build Data Views from your tables covers the other way to put a table on a Pegboard: tables, cards, and checklists, for when the rows are things to read rather than values to plot.