Dashboards

A dashboard is sections over tables, each narrowed by its own query and, with over, by the time window the reader picks.

dashboard('Sales', [
  metric('Won', 'opportunity', {
    query: 'stage = closed_won and close_date = last 90 days',
    measure: 'sum amount as won',
    compare: 'previous period', better: 'up', over: 'close_date', spark: true,
  }),
  chart('Bookings by month', 'opportunity', 'month close_date', { measure: 'sum amount' }),
  breakdown('Pipeline by stage', 'opportunity', 'stage', { width: 'half', over: 'close_date' }),
], { windows: ['last 30 days', 'last 90 days', 'last 12 months'] }),

Sections

metric, chart (shape: line, bar, donut, stacked), breakdown, matrix, rows, board, activity(), note, embed(view) and firstRun(). Each takes query (the query language without the table), measure (count, sum amount as won, avg, min, max, count distinct) and width (third, half, …); aside holds a column beside the main flow.

The window: over and windows

• A section with over: '<date column>' follows the picker; one without stays as its query says. over must be a date column.
• The dashboard’s windows are the picker’s choices, in the query grammar’s words; absent: last 30 days, last 90 days, last 12 months. The address keeps the pick (?period=last-30-days).
• A section’s own windows give it a picker of its own (?period.<its title as a slug>=last-7-days).
• When a section’s query already windows its over column (close_date = last 90 days), the reader’s pick replaces that phrase rather than narrowing within it. Until a pick, the author’s window stands.

compare and the picker

compare is a second query for the same measure; the card shows the change, and better: 'up' | 'down' colors it.

• compare: 'previous period' derives it from the query’s one last N days/weeks/months/years phrase, shifted back one length.
• A metric with no window phrase but an over follows the reader instead: the change is against the equal-length period before the picked window (the dashboard’s, or the section’s own windows), and under All time there is none. Two window phrases refuse.
• While the reader has picked last N …, it follows the pick: last 30 days compares with previous 30 days. A pick with no previous (this month) hides the change.
• A compare written in full is the author’s: it hides while a window is picked, since the reader’s window against the author’s is no change.
• better without compare colors nothing, and the check warns.

Periods

A chart or breakdown groups by a column, a path (owner_id.name) or a period of a date column: day, month, quarter or year (month close_date). There is no week bucket; last 12 weeks is a window, not a grouping.

Charts, rows and the rest on a record’s page: pages.